D03
Make your first request
Candidate documentation for reading and synthetic examples. Account creation, live API access, SDKs, collections and MCP are not available here. A released service profile and matching integration instructions are required before use.
For a single company reference, the candidate operation is resolveReference: POST /v1/resolutions. It returns an identity outcome and essential evidence. Retrieving relationships, hierarchy or classifications is a separate operation with its own permissions and usage treatment.
Send what you know. A name-only reference also needs an explicit supported search scope. A registration number or LEI must include the correct scheme and issuing context. Preserve identifier leading zeroes. Search scope, identifier jurisdiction and address country are different meanings; do not change one to disguise a conflict in another.
This request is synthetic and copied from the pinned contract example. 00000000 is not evidence of a real company or a successful match. Use it only in an explicitly synthetic demonstration. Open the complete synthetic request.
{
"reference": {
"name": "Example Demonstration Limited",
"subject_type": "legal_entity",
"search_scope": { "territories": ["GB"] },
"identifiers": [
{
"scheme": "GB_CH",
"authority": "COMPANIES_HOUSE",
"jurisdiction": "GB",
"value": "00000000",
"subject_type": "legal_entity"
}
]
}
}
The transport template below is for review. It has not been executed against a service. Bind each variable using the released integration instructions, and substitute an input you are permitted to use before a real request. The example does not provision credentials or select a live URL.
curl --request POST "${ENTITY_API_BASE_URL}/v1/resolutions" \
--header "Authorization: Bearer ${ENTITY_ACCESS_TOKEN}" \
--header "Content-Type: application/json" \
--header "Entity-Service-Profile: ${ENTITY_SERVICE_PROFILE}" \
--header "Idempotency-Key: ${ENTITY_OPERATION_KEY}" \
--header "Entity-Operation-Created-At: ${ENTITY_OPERATION_CREATED_AT}" \
--header "Entity-Max-Units: ${ENTITY_MAX_UNITS}" \
--data-binary @resolution-request.synthetic.json
| Value | What to supply |
|---|---|
ENTITY_API_BASE_URL |
The exact released API base URL for your authorised environment. |
ENTITY_ACCESS_TOKEN |
A valid access token with the required audience/scope; never an ID token or shared administrator credential. |
ENTITY_SERVICE_PROFILE |
The exact accepted profile_id from capabilities. The endpoint separately pins its immutable revision and contract binding; do not substitute a revision string for the profile ID. |
ENTITY_OPERATION_KEY |
One random UUID created for this logical operation. Preserve it for a retry of the same semantic request. |
ENTITY_OPERATION_CREATED_AT |
The original creation instant in the required date-time format, retained unchanged on retry. The profile’s admission/skew window applies. |
ENTITY_MAX_UNITS |
Your chosen ceiling in the accepted offer’s atomic unit. Use a canonical decimal integer string. It can reduce permitted spending, never increase account authority. This header is optional on this operation; this template includes it deliberately. |
Before running a live test, review the maximum charge and the applicable limits. If the service cannot provide a trustworthy bound or admission is unavailable, resolve that condition first. Repeated clicks, page reloads or switching code tabs must not create extra work.
A changed semantic input is a new operation. Reusing an old key for different input is a conflict. For a transport retry of unchanged input, preserve the original key, creation time, profile and applicable context; follow the service’s recovery instruction rather than generating a fresh key automatically.
Follow the same request through a complete example
The offline first-request walkthrough pairs this exact request with the complete synthetic response embedded in the same pinned resolveReference contract. Both values are unchanged and separately schema-validated. The response concerns Example Demonstration Limited, with the legal-name claim, identity assessment, evidence limitations and usage receipt available together. It is a stipulated illustration, not a response obtained by running a matching service.
Use this pair to learn the request/result structure before opening the separate HARBOUR LANE four-outcome reading exercise below. All three existing language readers produce the same summary for the contract response, including an isolated Elixir check. Twenty-one offline checks cover original-value equality, complete schemas, leading-zero preservation, invalid inputs, required header shapes and Python/TypeScript parity. Profile-specific limits, source rights, authentication, actual transport and charging remain release qualifications.
Before a real request, retain the unchanged input, original key and creation time with the selected profile context. If the acknowledgement is lost, follow D07 to reconcile that operation. The walkthrough does not call an endpoint or implement automatic retry.