Entity search

API documentation

Public asynchronous workflow for search, profile selection, and field drill-down.

Connect

Base URL: https://frank-prod-entity-search.datafabdevelopment.com. Every endpoint requires a valid bearer token.

export API_BASE_URL="https://frank-prod-entity-search.datafabdevelopment.com"
export TOKEN="replace-with-a-valid-bearer-token"

Keep tokens out of source code, screenshots, and shell history. All examples below use fictional data and placeholder IDs.

Response envelope and polling

Every response contains is_error, message,status_code, and results. Initiation calls return HTTP 202; poll the matching data endpoint every two seconds until results.status is COMPLETED orFAIL.

{
  "is_error": false,
  "message": "Human-readable status",
  "status_code": 200,
  "results": {}
}

1. Search entities

GET /v1/api/search/ requires entity_nameand entity_type (organization orperson). jurisdiction andsession_id are optional.

curl -G "$API_BASE_URL/v1/api/search/" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "entity_name=Example Holdings Ltd" \
  --data-urlencode "entity_type=organization" \
  --data-urlencode "jurisdiction=GB"

{
  "is_error": false,
  "message": "Search initiated",
  "status_code": 202,
  "results": {
    "request_id": "search-request-id",
    "task_id": "worker-task-id",
    "status": "INITIATED",
    "sub_status": "INITIATED",
    "session_id": null
  }
}

Poll GET /v1/api/search/data?request_id=search-request-id.

{
  "is_error": false,
  "message": "OK",
  "status_code": 200,
  "results": {
    "request_id": "search-request-id",
    "status": "COMPLETED",
    "sub_status": "SUCCESS",
    "results": [{ "identifier": "EXAMPLE-IDENTIFIER", "name": "Example Holdings Ltd" }]
  }
}

2. Select a profile

GET /v1/api/select/ requires the search resultidentifier and search_request_id.entity_type, jurisdiction, andsession_id are optional.

curl -G "$API_BASE_URL/v1/api/select/" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "identifier=EXAMPLE-IDENTIFIER" \
  --data-urlencode "search_request_id=search-request-id"

{
  "is_error": false,
  "message": "Select initiated",
  "status_code": 202,
  "results": {
    "request_id": "select-request-id",
    "identifier": "EXAMPLE-IDENTIFIER",
    "status": "INITIATED"
  }
}

Poll GET /v1/api/select/data?request_id=select-request-id. Completed responses return results.profile; itsresults.links keys are available field categories.

{
  "is_error": false,
  "message": "OK",
  "status_code": 200,
  "results": {
    "request_id": "select-request-id",
    "identifier": "EXAMPLE-IDENTIFIER",
    "status": "COMPLETED",
    "profile": { "results": { "links": { "directors": "available" } } }
  }
}

3. Drill into a field

GET /v1/api/field/ requires identifier, the selection request_id, and a field key returned by profile selection. entity_type andsession_id are optional.

curl -G "$API_BASE_URL/v1/api/field/" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "identifier=EXAMPLE-IDENTIFIER" \
  --data-urlencode "request_id=select-request-id" \
  --data-urlencode "field=directors"

{
  "is_error": false,
  "message": "Field initiated",
  "status_code": 202,
  "results": {
    "request_id": "field-request-id",
    "identifier": "EXAMPLE-IDENTIFIER",
    "field": "directors",
    "status": "INITIATED"
  }
}

Poll GET /v1/api/field/data?request_id=field-request-id.

{
  "is_error": false,
  "message": "OK",
  "status_code": 200,
  "results": {
    "request_id": "field-request-id",
    "identifier": "EXAMPLE-IDENTIFIER",
    "field": "directors",
    "status": "COMPLETED",
    "data": { "results": { "directors": [{ "name": "Example Director" }] } }
  }
}

Internal APIs

Service-to-service endpoints

These endpoints are for trusted service-to-service callers only. They do not use a bearer token. Send X-System-API-Key and keep the key in a secret manager or deployment environment.

export SYSTEM_API_KEY="replace-with-internal-api-key"
export TENANT_ID="tenant-id"
export USER_EMAIL="[email protected]"

Endpoint	Method	Required query parameters
`/v1/api/internal/health`	GET	None
`/v1/api/internal/search`	GET	Public search parameters, `tenant_id`, `user_email`
`/v1/api/internal/search/data`	GET	`request_id`, `tenant_id`
`/v1/api/internal/select`	GET	Public select parameters, `tenant_id`, `user_email`
`/v1/api/internal/select/data`	GET	`request_id`, `tenant_id`
`/v1/api/internal/field`	GET	Public field parameters, `tenant_id`, `user_email`
`/v1/api/internal/field/data`	GET	`request_id`, `tenant_id`
`/v1/api/internal/cache`	DELETE	`tenant_id`

Internal search, select, and field endpoints have the same response shapes and async polling workflow as their public counterparts.

curl -G "$API_BASE_URL/v1/api/internal/search" \
  -H "X-System-API-Key: $SYSTEM_API_KEY" \
  --data-urlencode "tenant_id=$TENANT_ID" \
  --data-urlencode "user_email=$USER_EMAIL" \
  --data-urlencode "entity_name=Example Holdings Ltd" \
  --data-urlencode "entity_type=organization"

curl -X DELETE "$API_BASE_URL/v1/api/internal/cache?tenant_id=$TENANT_ID" \
  -H "X-System-API-Key: $SYSTEM_API_KEY"

{
  "is_error": false,
  "message": "Cache cleared",
  "status_code": 200,
  "results": { "cleared": { "search": 1, "select": 1, "field": 1 } }
}

Errors

Missing or expired credentials return HTTP 401. A request ID that is missing or belongs to another tenant returns HTTP 404. Invalid or missing query parameters return HTTP 422. A request accepted with HTTP 202 can still finish with results.status: "FAIL"; inspect results.sub_status and do not continue the workflow.

Open generated API reference ↗