Skip to navigation
Entity Whitelisting

Create the Entity ID

View as Markdown

Through entity ID creation process you can create Entity IDs for the merchant whom you want to have the business establishment.

Use POST verb for Create action
- This endpoint support XML and JSON formats.
- You specify values for input parameters in the body of your XML/JSON document.
- You encrypt the payload, place it in your request and send it with your application.
Content-Type: Supports application/xml and application/json.
Authorization: The OAuth token prefixed with bearer and a space in between.

Authentication

AuthorizationBearer

All CitiConnect APIs use the oAuth2 authentication scheme, which requires a bearer token to authenticate your API call. The Token URL includes the version of authentication used by this API. See the Citi Authentication API reference for information on requesting a token.

Headers

Idempotency-IdstringRequired<=128 characters

Your unique identification for a POST request
- Maximum length is 128.
- CitiConnect API responds with an error (HTTP status 4XX) if your POST request idempotency identification value is a duplicate across a recent history of idempotency identifications in Citi’s database.
- If you don’t receive any response (HTTP status 2XX, 4XX or 5XX) from Citi to your POST request and you wish to retry, reinitiate your request with the same idempotency identification to prevent accidental duplicate payment.

Query parameters

client_idstringRequired<=40 characters

Unique reference shared during CitiConnect API onboarding (client_id used during OAuth token generation).

Request

Describes the entity ID creation endpoint request body parameters.
entityobjectRequired

Required object for both ‘CREATE’ (POST) and ‘UPDATE’ (PATCH) operations.

entity_idstringOptional=20 characters
Entity ID that was assigned during the 'CREATE' action under POST endpoint. This is a required parameter for the PATCH endpoint.
beneficial_ownerlist of objectsOptional

Parameters are applicable for both ‘POST’ and ‘PATCH’ endpoints.

Information for up to four (4) beneficial owners is allowed.
Maintain the beneficial owner details order as per their ownership with the entity.

- Not applicable for Sole Trader (entity.type=‘S’).

Response headers

DeprecationstringOptional

The date when the API was stopped or will be stopped by the system owner. ISO 8601-1:2019 format.

SunsetstringOptional

The date when the API will no longer be Supported by the system owner. The API will no longer be responsive and all REQUESTS will generate an error. ISO 8601-1:2019 format.

RateLimit-LimitstringOptional
The rate limit ceiling for that given request measured in a 24 hour cycle.
RateLimit-RemainingstringOptional
The number of requests left in a 15 minute window.
RateLimit-ResetstringOptional

The remaining window before the rate limit resets. ISO 8601-1:2019.

Response

EntityID response
request_idstringOptional1-40 characters

Auto-generated unique identification assigned for the request.

statusstringOptional1-20 characters
Status of the request.
messagestringOptional1-400 characters
Detailed response description for given request.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
405
Method Not Allowed Error
409
Conflict Error
415
Unsupported Media Type Error
429
Too Many Requests Error
500
Internal Server Error