openapi: 3.2.0 info: title: Add-on Services Addonservices API description: CitiConnect API service sometimes allows you to perform the Entity ID (NCLE - Non-Client Legal Entity) creation functionality directly from your Client ERP System. contact: name: Standards & Developer Hub url: https://tts.sandbox.developer.citi.com/citiconnect/ email: developer-support@citi.com version: 1.0.0 servers: - url: https://b2b.tts.icgservices.citi.com/citiconnect/prod description: production gateway url tags: - name: Addonservices paths: /addonservices/v1/entityids: post: summary: Create the Entity/NCLE ID description: 'Through entity ID creation process, you can create entity/NCLE IDs for the merchant with whom you want to establish a business relationship. Use POST verb for Create action - The API supports 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.' operationId: createEntityId parameters: - $ref: '#/components/parameters/Client-Id' - $ref: '#/components/parameters/Idempotency-Id' requestBody: description: Describes the entity (NCLE) ID creation APIs request body parameters. content: application/json: schema: $ref: '#/components/schemas/Entity-Id-Request' examples: EntityIDCreateExample: $ref: '#/components/examples/EntityID-Create-Request-Example' application/xml: schema: $ref: '#/components/schemas/Entity-Id-Request' examples: EntityIDCreateExample: $ref: '#/components/examples/EntityID-Create-Request-Example' responses: '202': $ref: '#/components/responses/Entity-Id-202-Response' '400': $ref: '#/components/responses/Ncle-Bad-Request' '401': $ref: '#/components/responses/Ncle-Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Ncle-Not-Found' '405': $ref: '#/components/responses/Ncle-Method-Not-Allowed' '409': $ref: '#/components/responses/Idempotency-Duplication' '415': $ref: '#/components/responses/Ncle-Unsupported-Media-Type' '429': $ref: '#/components/responses/Too-Many-Request' '500': $ref: '#/components/responses/Ncle-Internal-Server-Error' security: - Client Credentials: [] callbacks: EntityIdPostAsyncResponse: $ref: '#/components/callbacks/EntityId-Create-Async-Response' tags: - Addonservices patch: summary: Update the Entity/NCLE details description: 'Through the entity ID creation process you can update Entity / NCLE details pertaining the merchant. Use PATCH verb for Update action - The API 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 space in between.' operationId: modifyEntityId parameters: - $ref: '#/components/parameters/Client-Id' requestBody: description: Describes the entity (NCLE) ID creation APIs request body parameters. content: application/json: schema: $ref: '#/components/schemas/Entity-Id-Request' examples: EntityIDUpdateExample: $ref: '#/components/examples/EntityID-Update-Request-Example' application/xml: schema: $ref: '#/components/schemas/Entity-Id-Request' examples: EntityIDUpdateExample: $ref: '#/components/examples/EntityID-Update-Request-Example' responses: '202': $ref: '#/components/responses/Entity-Id-202-Response' '400': $ref: '#/components/responses/Ncle-Bad-Request' '401': $ref: '#/components/responses/Ncle-Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Ncle-Not-Found' '405': $ref: '#/components/responses/Ncle-Method-Not-Allowed' '415': $ref: '#/components/responses/Ncle-Unsupported-Media-Type' '429': $ref: '#/components/responses/Too-Many-Request' '500': $ref: '#/components/responses/Ncle-Internal-Server-Error' security: - Client Credentials: [] callbacks: EntityIdPatchAsyncResponse: $ref: '#/components/callbacks/EntityId-Update-Async-Response' tags: - Addonservices get: summary: Check the Entity/NCLE ID status and details description: 'The entity ID inquiry endpoint can be used primarily for entity / NCLE ID status check as well as information purposes. Use GET verb for Inquiry action - The API support XML and JSON formats. - You specify the response format needed in Accept header. Content-Type : Supports application/xml and application/json. Authorization : The OAuth Token prefixed with Bearer and space in between.' operationId: getEntityDetails parameters: - $ref: '#/components/parameters/Client-Id' - $ref: '#/components/parameters/Entity-Id' - $ref: '#/components/parameters/Country-Of-Operation' responses: '200': $ref: '#/components/responses/Entity-Id-Sync-Response' '400': $ref: '#/components/responses/Bad-Sync-Request' '401': $ref: '#/components/responses/Ncle-Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Ncle-Not-Found' '429': $ref: '#/components/responses/Too-Many-Request' '500': $ref: '#/components/responses/Ncle-Internal-Server-Error' tags: - Addonservices components: examples: Bad-Request-Xml-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - code: VC00012 issue: Provided value is not within the range for query-param entity_id action: Please provide valid value for query-param entity_id, size must be between 20 and 20 Gateway-Internal-Server-Error-Example: value: status: '500' message: Internal Server Error Ncle-Internal-Server-Error-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - code: CC00004 issue: Unable to serve your request at this moment action: Please refer to documentation provided or contact support team EntityID-Create-Request-Example: value: entity: last_name: INC first_name: ABC type: C date_of_birth: '2024-05-01' website: www.dd.com store_name: ABC business_purpose: Trade acronym: Buss country_of_operation: US org_prvt_identification: type: TAX_ID id: '1234567890' country_of_issuance: US address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US beneficial_owner: - last_name: James first_name: White date_of_birth: '2001-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US - last_name: Mark first_name: White date_of_birth: '2000-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US EntityId-Create-Async-Pending-Response-Example: value: request_id: ec689822-9864-4c4d-9d68-222467627902 entity_id: 9CT5RGG9NPBE60M entity_status: PENDING entity: last_name: INC first_name: ABC type: C date_of_birth: '2024-05-01' website: www.dd.com store_name: ABC business_purpose: Trade acronym: Buss country_of_operation: US org_prvt_identification: type: TAX_ID id: '1234567890' country_of_issuance: US address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: Cuba country_sub_division: Ontario country: US beneficial_owner: - last_name: James first_name: White date_of_birth: '2001-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US Idempotency-Duplication-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - code: VC00016 issue: Idempotency-Id provided is currently being used in another request action: Please do not repeat the same request again Bad-Request-Xml-Sync-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - code: VC00012 issue: Provided value is not within the range for property entity.address.street_name action: Please provide valid value for property entity.type, size must be between 1 and 70 EntityID-Update-Request-Example: value: entity_id: A1234567890123456789 entity: last_name: INC first_name: ABC type: C date_of_birth: '2024-05-01' website: www.dd.com store_name: ABC business_purpose: Trade acronym: Buss country_of_operation: US org_prvt_identification: type: TAX_ID id: '1234567890' country_of_issuance: US address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US beneficial_owner: - last_name: James first_name: White date_of_birth: '2001-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US - last_name: Mark first_name: White date_of_birth: '2000-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US EntityId-Create-Async-Success-Response-Example: value: request_id: ec689822-9864-4c4d-9d68-222467627902 entity_id: 9CT5RGG9NPBE60M entity_status: SUCCESS entity: last_name: INC first_name: ABC type: C date_of_birth: '2024-05-01' website: www.dd.com store_name: ABC business_purpose: Trade acronym: Buss country_of_operation: US org_prvt_identification: type: TAX_ID id: '1234567890' country_of_issuance: US address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US beneficial_owner: - last_name: James first_name: White date_of_birth: '2001-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US EntityId-Update-Async-Pending-Response-Example: value: request_id: ec689822-9864-4c4d-9d68-222467627902 entity_id: 9CT5RGG9NPBE60M entity_status: PENDING entity: last_name: INC first_name: ABC type: C date_of_birth: '2024-05-01' website: www.dd.com store_name: ABC business_purpose: Trade acronym: Buss country_of_operation: US org_prvt_identification: type: TAX_ID id: '1234567890' country_of_issuance: US address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: Cuba country_sub_division: Ontario country: US beneficial_owner: - last_name: James first_name: White date_of_birth: '2001-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US Gateway-Un-Authorized: value: httpCode: '401' httpMessage: Unauthorized moreInformation: Invalid client identification Unsupported-Media-Type-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - code: CC00002 issue: Media type not supported action: Please use valid content-type in header EntityId-Create-Async-Reject-Response-Example: value: request_id: ec689822-9864-4c4d-9d68-222467627902 entity_id: 9CT5RGG9NPBE60M entity_status: REJECTED entity: last_name: INC first_name: ABC type: C date_of_birth: '2024-05-01' website: www.dd.com store_name: ABC business_purpose: Trade acronym: Buss country_of_operation: US org_prvt_identification: type: TAX_ID id: '1234567890' country_of_issuance: US address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: Cuba country_sub_division: Ontario country: US beneficial_owner: - last_name: James first_name: White date_of_birth: '2001-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US Entity-Id-Response-Example: value: request_id: ec689822-9864-4c4d-9d68-222467627902 status: CREATED message: Request accepted Successfully EntityId-Update-Async-Success-Response-Example: value: request_id: ec689822-9864-4c4d-9d68-222467627902 entity_id: 9CT5RGG9NPBE60M entity_status: SUCCESS entity: last_name: INC first_name: ABC type: C date_of_birth: '2024-05-01' website: www.dd.com store_name: ABC business_purpose: Trade acronym: Buss country_of_operation: US org_prvt_identification: type: TAX_ID id: '1234567890' country_of_issuance: US address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US beneficial_owner: - last_name: James first_name: White date_of_birth: '2001-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US Forbidden-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - code: CC00008 issue: User does not have privilege to access this functionality action: Please reach out to support team to enable this feature Gateway-Method-Not-Allowed-Example: value: httpCode: '405' httpMessage: Method Not Allowed moreInformation: The method is not allowed for the requested URL Entity-Id-Sync-Success-Response-Example: value: entity_id: 9CT5RGG9NPBE60M entity_status: SUCCESS entity: - last_name: INC first_name: ABC type: C date_of_birth: '2024-05-01' website: www.dd.com store_name: ABC business_purpose: Trade acronym: Buss country_of_operation: US org_prvt_identification: type: TAX_ID id: '1234567890' country_of_issuance: US address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US beneficial_owner: - last_name: James first_name: White date_of_birth: '2001-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US Entity-Id-Sync-Reject-Response-Example: value: entity_id: 9CT5RGG9NPBE60M entity_status: REJECTED entity: - last_name: INC first_name: ABC type: C date_of_birth: '2024-05-01' website: www.dd.com store_name: ABC business_purpose: Trade acronym: Buss country_of_operation: US org_prvt_identification: type: TAX_ID id: '1234567890' country_of_issuance: US address: street_name: 125 Oain st building_number: 155/356 postal_code: '14526369' town_name: cuba country_sub_division: NC32 country: US beneficial_owner: - last_name: James first_name: White date_of_birth: '2001-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US Bad-Request-Json-Sync-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - code: VC00012 issue: Provided value is not within the range for query-param entity_id action: Please provide valid value for query-param entity_id, size must be between 20 and 20 Bad-Request-Json-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - code: VC00012 issue: Provided value is not within the range for property entity.address.street_name action: Please provide valid value for property entity.type, size must be between 1 and 70 Ncle-Not-Found-Example: value: httpCode: '404' httpMessage: Not Found moreInformation: No resources match requested URI EntityId-Update-Async-Reject-Response-Example: value: request_id: ec689822-9864-4c4d-9d68-222467627902 entity_id: 9CT5RGG9NPBE60M entity_status: REJECTED entity: last_name: INC first_name: ABC type: C date_of_birth: '2024-05-01' website: www.dd.com store_name: ABC business_purpose: Trade acronym: Buss country_of_operation: US org_prvt_identification: type: TAX_ID id: '1234567890' country_of_issuance: US address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: Cuba country_sub_division: Ontario country: US beneficial_owner: - last_name: James first_name: White date_of_birth: '2001-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US Ncle-Method-Not-Allowed-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - code: CC00007 issue: Method Not Allowed action: Please use valid method type Entity-Id-Sync-Pending-Response-Example: value: entity_id: 9CT5RGG9NPBE60M entity_status: PENDING entity: - last_name: INC first_name: ABC type: C date_of_birth: '2024-05-01' website: www.dd.com store_name: ABC business_purpose: Trade acronym: Buss country_of_operation: US org_prvt_identification: type: TAX_ID id: '1234567890' country_of_issuance: US address: street_name: 125 Oain st building_number: 155/356 postal_code: '14526369' town_name: cuba country_sub_division: NC32 country: US beneficial_owner: - last_name: James first_name: White date_of_birth: '2001-05-01' address: street_name: 3100 Keele st building_number: '533' postal_code: L5B 3Y6 town_name: North York country_sub_division: Ontario country: US Too-Many-Request-Example: value: status: '429' message: Requests are exceeding the allowed limit Ncle-Unauthorized-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - code: CC00007 issue: User does not have authorization to access action: Please use valid credentials to access this functionality - code: CC00007 issue: User does not have authorization to access action: Please use valid credentials to access this functionality EntityId-Async-Failure-Response-Example: value: request_id: 29b9c9d7-d4d9-48ce-8823-f9b3ee276b8f error_details: - code: NCLSS01 issue: Client Name is mandatory action: Populate client name and Resend schemas: Beneficial-Owner: title: BeneficialOwner xml: name: BeneficialOwner allOf: - $ref: '#/components/schemas/Contact-Name-BO' - type: object - required: - date_of_birth - address properties: date_of_birth: title: date_of_birth xml: name: DateOfBirth type: string minLength: 10 maxLength: 10 pattern: ^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$ description: Mandatory parameter under 'Beneficial Owner' object if the object is used.
Populates the date of birth date pertaining to the Beneficial owner of the entity. It is in fixed 10 digit format(YYYY-MM-DD) as per ISO format.

- Non-Modifiable parameter under 'PATCH' endpoint. example: '1980-04-01' address: $ref: '#/components/schemas/Ncle-Address' Entity-Id-Response: title: EntityIdResponse type: object xml: name: EntityIdResponse properties: request_id: $ref: '#/components/schemas/Request-Id' status: title: status xml: name: Status type: string minLength: 1 maxLength: 20 description: Status of the request. example: ACCEPTED message: title: message xml: name: Message type: string minLength: 1 maxLength: 400 description: Detailed response description for given request. example: Request accepted Successfully Contact-Name-Entity: title: Contact-Name-Entity xml: name: ContactNameEntity type: object required: - last_name properties: first_name: title: first_name xml: name: FirstName type: string minLength: 1 maxLength: 105 description: First name of entity linked to the merchant.
Further `entity.type` level applicability is mentioned below,

- Conditionally mandatory for Sole Trader (`entity.type`='S')
- Not applicable for Company (`entity.type`='C').

- Modifiable parameter under 'PATCH' endpoint. example: John last_name: title: last_name xml: name: LastName type: string minLength: 1 maxLength: 105 description: Last name of entity linked to the merchant.

- For Sole Trader (`entity.type`='S') - include the last name
- For Company (`entity.type`='C') - include the Legal Entity Name.

- Modifiable parameter under 'PATCH' endpoint. example: Thomas Apim-Json-Error: title: ApimJsonError xml: name: ApimJsonError type: object properties: status: title: status xml: name: Status type: string description: Http status code of the API response message: title: message xml: name: Message type: string description: Short message about the issue Apim-Error: title: ApimError xml: name: ApimError type: object properties: httpCode: title: httpCode xml: name: HttpCode type: string description: http staus code of the API httpMessage: title: httpMessage xml: name: HttpMessage type: string description: short message about the issue moreInformation: title: moreInformation xml: name: MoreInformation type: string description: more information about the issue Ncle-Error-Detail: title: ErrorDetail type: object xml: name: ErrorDetail properties: code: title: code xml: name: Code type: string maxLength: 7 description: Unique ID for the error code issue: title: issue xml: name: Issue type: string description: more details about the issue maxLength: 200 action: title: action xml: name: Action type: string description: corrective action to be taken to resolve above issue maxLength: 350 Request-Id: title: request_id xml: name: RequestId type: string minLength: 1 maxLength: 40 description: Auto-generated unique identification assigned for the request. example: 29b9c9d7-d4d9-48ce-8823-f9b3ee276b8f Organisation-Private-Identification: title: OrganisationPrivateIdentification xml: name: OrganisationPrivateIdentification type: object required: - type - id - country_of_issuance description: Non-Modifiable parameter under 'PATCH' endpoint. properties: type: title: type xml: name: Type type: string enum: - TAX_ID description: Type of the identification that is provided below in this object. Type maximum length can be up to 200 characters. - 'TAX_ID' Tax Identification

- Non-Modifiable parameter under 'PATCH' endpoint. example: TAX_ID id: title: id xml: name: Id type: string minLength: 1 maxLength: 255 description: Identification pertaining to the entity.

- Non-Modifiable parameter under 'PATCH' endpoint. example: '1234567890' country_of_issuance: title: country_of_issuance xml: name: CountryOfIssuance type: string minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ description: Country code where the provided identification has been issued.

- Non-Modifiable parameter under 'PATCH' endpoint. example: US Entity-Id-Request: title: EntityIDRequest xml: name: EntityIDRequest required: - entity type: object properties: entity_id: title: EntityId xml: name: EntityId description: Entity ID that was assigned during the 'CREATE' action under POST endpoint. Mandatory input for PATCH endpoint type: string maxLength: 20 minLength: 20 example: A1234567890123456789 entity: $ref: '#/components/schemas/Entity' beneficial_owner: title: BeneficialOwner description: Parameters are applicable for both 'POST' and 'PATCH' endpoints.

Up to 4 beneficial owner information can be given.
Maintain the beneficial owner details order as per their ownership with the entity.

- Not applicable for sole trader (`entity.type`='S') xml: name: BeneficialOwner wrapped: true type: array minItems: 1 maxItems: 4 items: $ref: '#/components/schemas/Beneficial-Owner' Entity-Id-Sync-Response: title: EntityIdResponse type: object xml: name: EntityIdResponse properties: entity_id: title: entity_id xml: name: EntityId type: string maxLength: 20 minLength: 1 example: A90184799234242 entity_status: title: entity_status xml: name: EntityStatus type: string minLength: 1 maxLength: 20 description: Status of the request.
Possible statuses are
PENDING
SUCCESS
REJECTED example: SUCCESS entity: title: entity xml: name: Entity wrapped: true type: array items: $ref: '#/components/schemas/Entity-Sync' Entity: title: Entity description: Mandatory object for both 'CREATE' (POST) and 'UPDATE' (PATCH) action values. xml: name: Entity allOf: - $ref: '#/components/schemas/Contact-Name-Entity' - type: object - required: - country_of_operation - address - org_prvt_identification - date_of_birth - type properties: type: title: type xml: name: Type type: string enum: - C - S description: Mandatory parameter for POST endpoint.
Populate the entity type applicable for the entity / merchant.

C = COMPANY

S = SOLE TRADER - enterprise owned and run by one person and in which there is no legal distinction between the owner and the business entity.

- Non-Modifiable parameter under 'PATCH' endpoint. example: C date_of_birth: title: date_of_birth xml: name: DateOfBirth type: string minLength: 10 maxLength: 10 pattern: ^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$ description: Mandatory parameter for POST endpoint.
Populates the date of birth or incorporation date pertaining to the entity that is being activated under this Entity. It is in fixed 10 digit format(YYYY-MM-DD) as per ISO format.

- Non-Modifiable parameter under 'PATCH' endpoint. example: '1996-06-25' website: title: website xml: name: Website type: string minLength: 0 maxLength: 200 description: Populate the website of entity.

- Modifiable parameter under 'PATCH' endpoint. example: http://www.dd.com store_name: title: store_name xml: name: StoreName type: string minLength: 0 maxLength: 105 description: Populate the store name of entity.

- Modifiable parameter under 'PATCH' endpoint. example: ABC business_purpose: title: business_purpose xml: name: BusinessPurpose type: string minLength: 0 maxLength: 105 description: Populate the business purpose applicable.

- Modifiable parameter under 'PATCH' endpoint. example: Trade acronym: title: acronym xml: name: Acronym type: string minLength: 0 maxLength: 105 description: Populate the acronym for the Entity.

- Modifiable parameter under 'PATCH' endpoint. example: Buss country_of_operation: title: country_of_operation xml: name: CtryOfOpr type: string minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ description: Enter the 'Country code' on which the entity is operated.

- Non-Modifiable parameter under 'PATCH' endpoint. example: US org_prvt_identification: $ref: '#/components/schemas/Organisation-Private-Identification' address: $ref: '#/components/schemas/Ncle-Address' Contact-Name-BO: title: Contact-Name-BO xml: name: ContactNameBO type: object required: - first_name - last_name properties: first_name: title: first_name xml: name: FirstName type: string minLength: 1 maxLength: 105 description: First name of Beneficial Owner linked to the merchant.

- Modifiable parameter under 'PATCH' endpoint. example: John last_name: title: last_name xml: name: LastName type: string minLength: 1 maxLength: 105 description: Last name of Beneficial Owner linked to the merchant.

- Modifiable parameter under 'PATCH' endpoint. example: Thomas EntityId-Async-Response: title: EntityIDAsyncResponse xml: name: EntityIDResponse required: - request_id type: object properties: request_id: title: request_id xml: name: RequestId type: string description: Auto-generated unique identification assigned for the request. entity_id: title: entity_id xml: name: EntityId type: string description: Entity (NCLE) ID that is assigned specific for the merchant entity_status: title: entity_status xml: name: EntityStatus type: string minLength: 1 maxLength: 30 description: Status of the Entity (NCLE) ID.
Possible statuses are
PENDING
SUCCESS
REJECTED example: SUCCESS entity: $ref: '#/components/schemas/Entity' beneficial_owner: title: BeneficialOwner description: Beneficial Owners of the given merchant xml: name: BeneficialOwner wrapped: true type: array minItems: 1 maxItems: 4 items: $ref: '#/components/schemas/Beneficial-Owner' error_details: title: error_details type: array xml: name: ErrorDetails wrapped: true items: $ref: '#/components/schemas/Ncle-Error-Detail' Error-Message: title: ErrorMessage xml: name: ErrorMessage description: description of error type: object properties: ref_id: type: string title: ref_id xml: name: RefId maxLength: 60 pattern: \w*\W* description: Unique reference ID for particular request error_details: title: error_details type: array xml: name: ErrorDetails wrapped: true items: $ref: '#/components/schemas/Ncle-Error-Detail' Entity-Sync: title: Entity description: Entity details provided during 'CREATE' (POST) and 'UPDATE' (PATCH) operation. xml: name: Entity allOf: - $ref: '#/components/schemas/Contact-Name-Entity' - type: object - required: - country_of_operation - address - org_prvt_identification - date_of_birth properties: type: title: type xml: name: Type type: string enum: - C - S description: Type of the entity populated during the entity creation.

C = COMPANY

S = SOLE TRADER - enterprise owned and run by one person and in which there is no legal distinction between the owner and the business entity. example: C date_of_birth: title: date_of_birth xml: name: DateOfBirth type: string minLength: 10 maxLength: 10 pattern: ^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$ description: Date of birth or incorporation date of the entity populated during the entity creation. example: '1996-06-25' website: title: website xml: name: Website type: string minLength: 0 maxLength: 200 description: Website of entity provided during the entity creation. example: http://www.dd.com store_name: title: store_name xml: name: StoreName type: string minLength: 0 maxLength: 105 description: Store name of entity provided during the entity creation or update. example: ABC business_purpose: title: business_purpose xml: name: BusinessPurpose type: string minLength: 0 maxLength: 105 description: Business purpose provided during the entity creation or update. example: Trade acronym: title: acronym xml: name: Acronym type: string minLength: 0 maxLength: 105 description: Acronym for the entity provided during the entity creation or update. example: Buss country_of_operation: title: country_of_operation xml: name: CtryOfOpr type: string minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ description: Country code of where the entity is operated. example: US org_prvt_identification: $ref: '#/components/schemas/Organisation-Private-Identification' address: $ref: '#/components/schemas/Ncle-Address' beneficial_owner: title: BeneficialOwner description: beneficiary owner details provided during 'CREATE' (POST) and 'UPDATE' (PATCH) operation.

- Not applicable for Sole Trader (`entity.type`='S') xml: name: BeneficialOwner wrapped: true type: array minItems: 1 maxItems: 4 items: $ref: '#/components/schemas/Beneficial-Owner' Ncle-Address: title: Address xml: name: Address type: object required: - street_name - building_number - postal_code - town_name - country_sub_division - country description: Address object is mandatory if `entity` object is used. properties: street_name: title: street_name xml: name: StrtNm type: string minLength: 1 maxLength: 70 description: Address details of entity (or) Beneficial owner of entity. Mandatory parameter under `Address` object.

- Modifiable parameter under 'PATCH' endpoint. example: 3100 Keele st building_number: title: building_number xml: name: BldgNb type: string minLength: 1 maxLength: 16 description: Address details of entity (or) Beneficial owner of entity.

- Modifiable parameter under 'PATCH' endpoint. example: '533' postal_code: title: postal_code xml: name: PstCd type: string minLength: 1 maxLength: 16 description: Address details of entity (or) Beneficial owner of entity. Mandatory parameter under `Address` object.

- Modifiable parameter under 'PATCH' endpoint. example: L5B 3Y6 town_name: title: town_name xml: name: TwnNm type: string minLength: 1 maxLength: 35 description: Address details of entity (or) Beneficial owner of entity. Mandatory parameter under `Address` object.

- Modifiable parameter under 'PATCH' endpoint. example: North York country_sub_division: title: country_sub_division xml: name: CtrySubDvsn type: string minLength: 1 maxLength: 35 description: Address details of Entity (or) Beneficial owner of entity. Mandatory parameter under `Address` object.

- Modifiable parameter under 'PATCH' endpoint. example: Ontario country: title: country xml: name: Ctry type: string minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ description: Address details of Entity (or) Beneficial owner of Entity. Mandatory parameter under `Address` object.

- Modifiable parameter under 'PATCH' endpoint. example: US responses: Ncle-Bad-Request: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error-Message' examples: BadRequest: $ref: '#/components/examples/Bad-Request-Json-Example' application/xml: schema: $ref: '#/components/schemas/Error-Message' examples: BadRequest: $ref: '#/components/examples/Bad-Request-Xml-Example' Ncle-Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error-Message' examples: Unauthorized: $ref: '#/components/examples/Ncle-Unauthorized-Example' GatewayUnauthorized: $ref: '#/components/examples/Gateway-Un-Authorized' application/xml: schema: $ref: '#/components/schemas/Error-Message' examples: Unauthorized: $ref: '#/components/examples/Ncle-Unauthorized-Example' GatewayUnauthorized: $ref: '#/components/examples/Gateway-Un-Authorized' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error-Message' examples: Forbidden: $ref: '#/components/examples/Forbidden-Example' application/xml: schema: $ref: '#/components/schemas/Error-Message' examples: Forbidden: $ref: '#/components/examples/Forbidden-Example' Bad-Sync-Request: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error-Message' examples: BadRequest: $ref: '#/components/examples/Bad-Request-Json-Sync-Example' application/xml: schema: $ref: '#/components/schemas/Error-Message' examples: BadRequest: $ref: '#/components/examples/Bad-Request-Xml-Sync-Example' Ncle-Not-Found: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Apim-Error' examples: NotFound: $ref: '#/components/examples/Ncle-Not-Found-Example' application/xml: schema: $ref: '#/components/schemas/Apim-Error' examples: NotFound: $ref: '#/components/examples/Ncle-Not-Found-Example' Too-Many-Request: description: Too Many Request content: application/json: schema: $ref: '#/components/schemas/Apim-Json-Error' examples: TooManyRequest: $ref: '#/components/examples/Too-Many-Request-Example' application/xml: schema: $ref: '#/components/schemas/Apim-Json-Error' examples: TooManyRequest: $ref: '#/components/examples/Too-Many-Request-Example' Entity-Id-Sync-Response: description: EntityID Sync response headers: apim-guid: schema: type: string description: Citi's unique identification for your request Deprecation: description: The date when the API was stopped or will be stopped by the system owner. ISO 8601-1:2019 format. schema: type: string format: date-time Sunset: description: 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. schema: type: string format: date-time Link: description: Latest working url that can be used for the same purpose. schema: type: string RateLimit-Limit: description: The rate limit ceiling for that given request measured in a 24 hour cycle. schema: type: string RateLimit-Remaining: description: The number of requests left in a 15 minute window. schema: type: string RateLimit-Reset: description: The remaining window before the rate limit resets. ISO 8601-1:2019. schema: type: string format: date-time content: application/json: schema: $ref: '#/components/schemas/Entity-Id-Sync-Response' examples: SynchronousSuccessResponseExample: $ref: '#/components/examples/Entity-Id-Sync-Success-Response-Example' SynchronousPendingResponseExample: $ref: '#/components/examples/Entity-Id-Sync-Pending-Response-Example' SynchronousRejectResponseExample: $ref: '#/components/examples/Entity-Id-Sync-Reject-Response-Example' application/xml: schema: $ref: '#/components/schemas/Entity-Id-Sync-Response' examples: SynchronousSuccessResponseExample: $ref: '#/components/examples/Entity-Id-Sync-Success-Response-Example' SynchronousPendingResponseExample: $ref: '#/components/examples/Entity-Id-Sync-Pending-Response-Example' SynchronousRejectResponseExample: $ref: '#/components/examples/Entity-Id-Sync-Reject-Response-Example' Ncle-Unsupported-Media-Type: description: Unsupported Media Type content: application/json: schema: $ref: '#/components/schemas/Error-Message' examples: UnsupportedMediaType: $ref: '#/components/examples/Unsupported-Media-Type-Example' application/xml: schema: $ref: '#/components/schemas/Error-Message' examples: UnsupportedMediaType: $ref: '#/components/examples/Unsupported-Media-Type-Example' Ncle-Method-Not-Allowed: description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error-Message' examples: MethodNotAllowed: $ref: '#/components/examples/Ncle-Method-Not-Allowed-Example' GatewayMethodNotAllowed: $ref: '#/components/examples/Gateway-Method-Not-Allowed-Example' application/xml: schema: $ref: '#/components/schemas/Error-Message' examples: MethodNotAllowed: $ref: '#/components/examples/Ncle-Method-Not-Allowed-Example' GatewayMethodNotAllowed: $ref: '#/components/examples/Gateway-Method-Not-Allowed-Example' Entity-Id-202-Response: description: EntityID response headers: Deprecation: description: The date when the API was stopped or will be stopped by the system owner. ISO 8601-1:2019 format. schema: type: string format: date-time Sunset: description: 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. schema: type: string format: date-time Link: description: Latest working url that can be used for the same purpose. schema: type: string RateLimit-Limit: description: The rate limit ceiling for that given request measured in a 24 hour cycle. schema: type: string RateLimit-Remaining: description: The number of requests left in a 15 minute window. schema: type: string RateLimit-Reset: description: The remaining window before the rate limit resets. ISO 8601-1:2019. schema: type: string format: date-time content: application/json: schema: $ref: '#/components/schemas/Entity-Id-Response' examples: SynchronousResponseExample: $ref: '#/components/examples/Entity-Id-Response-Example' application/xml: schema: $ref: '#/components/schemas/Entity-Id-Response' examples: SynchronousResponseExample: $ref: '#/components/examples/Entity-Id-Response-Example' Idempotency-Duplication: description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error-Message' examples: IdempotencyDuplicationExample: $ref: '#/components/examples/Idempotency-Duplication-Example' application/xml: schema: $ref: '#/components/schemas/Error-Message' examples: IdempotencyDuplicationExample: $ref: '#/components/examples/Idempotency-Duplication-Example' Ncle-Internal-Server-Error: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error-Message' examples: InternalServerError: $ref: '#/components/examples/Ncle-Internal-Server-Error-Example' GatewayInternalServerError: $ref: '#/components/examples/Gateway-Internal-Server-Error-Example' application/xml: schema: $ref: '#/components/schemas/Error-Message' examples: InternalServerError: $ref: '#/components/examples/Ncle-Internal-Server-Error-Example' GatewayInternalServerError: $ref: '#/components/examples/Gateway-Internal-Server-Error-Example' parameters: Event-Name: name: Event-Name in: header required: true description: Describes the PUSH Notification (webhook) event name schema: type: string maxLength: 20 minLength: 1 example: Status Update Idempotency-Id: name: Idempotency-Id in: header description: 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. required: true schema: type: string maxLength: 128 example: a44cbb606de4edb9a7a123414bba3bb Entity-Id: name: entity_id in: query description: '`entity_id` that was assigned during the ''CREATE'' action under ''POST'' endpoint.' required: true schema: type: string maxLength: 20 minLength: 20 example: A1234567890123456789 Country-Of-Operation: name: country_of_operation in: query description: Country code of where the entity is operated. 2 digit ISO code which was entered during the creation process required: true schema: type: string maxLength: 2 minLength: 2 example: US pattern: ^[A-Z]{2}$ Event-Type: name: Event-Type in: header required: true description: Describes the PUSH Notification (webhook) event type schema: type: string maxLength: 20 minLength: 1 example: VAMAPI Apim-Guid: name: Apim-Guid in: header required: true description: Unique system generated reference number, refer this number incase of any discrepancy reporting to Citi representative schema: type: string maxLength: 52 minLength: 1 example: na-apimgwgtds04~4a98cbc5-d813-4e65-bc81-d70f0f87f6ec Client-Id: name: client_id in: query description: Unique reference shared during CitiConnect API onboarding (`client_id` used during OAuth token generation). required: true schema: type: string maxLength: 40 example: f56f0f6b-74fe-4dfa-b4ab-0da35a46b65e callbacks: EntityId-Create-Async-Response: '{$notificationURL}': post: parameters: - $ref: '#/components/parameters/Apim-Guid' - $ref: '#/components/parameters/Event-Type' - $ref: '#/components/parameters/Event-Name' description: Periodical status updates gets triggered in an asynchronous manner (Webhook / PUSH Notifications) to the notificationURL that client shared requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EntityId-Async-Response' examples: AsynchronousSuccessResponseExample: $ref: '#/components/examples/EntityId-Create-Async-Success-Response-Example' AsynchronousPendingResponseExample: $ref: '#/components/examples/EntityId-Create-Async-Pending-Response-Example' AsynchronousRejectResponseExample: $ref: '#/components/examples/EntityId-Create-Async-Reject-Response-Example' AsynchronousFailureResponseExample: $ref: '#/components/examples/EntityId-Async-Failure-Response-Example' application/xml: schema: $ref: '#/components/schemas/EntityId-Async-Response' examples: AsynchronousSuccessResponseExample: $ref: '#/components/examples/EntityId-Create-Async-Success-Response-Example' AsynchronousPendingResponseExample: $ref: '#/components/examples/EntityId-Create-Async-Pending-Response-Example' AsynchronousRejectResponseExample: $ref: '#/components/examples/EntityId-Create-Async-Reject-Response-Example' AsynchronousFailureResponseExample: $ref: '#/components/examples/EntityId-Async-Failure-Response-Example' responses: '202': description: Accepted content: application/json: schema: type: object EntityId-Update-Async-Response: '{$notificationURL}': post: parameters: - $ref: '#/components/parameters/Apim-Guid' - $ref: '#/components/parameters/Event-Type' - $ref: '#/components/parameters/Event-Name' description: Periodical status updates gets triggered in an asynchronous manner (Webhook / PUSH Notifications) to the notificationURL that client shared requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EntityId-Async-Response' examples: AsynchronousSuccessResponseExample: $ref: '#/components/examples/EntityId-Update-Async-Success-Response-Example' AsynchronousPendingResponseExample: $ref: '#/components/examples/EntityId-Update-Async-Pending-Response-Example' AsynchronousRejectResponseExample: $ref: '#/components/examples/EntityId-Update-Async-Reject-Response-Example' AsynchronousFailureResponseExample: $ref: '#/components/examples/EntityId-Async-Failure-Response-Example' application/xml: schema: $ref: '#/components/schemas/EntityId-Async-Response' examples: AsynchronousSuccessResponseExample: $ref: '#/components/examples/EntityId-Update-Async-Success-Response-Example' AsynchronousPendingResponseExample: $ref: '#/components/examples/EntityId-Update-Async-Pending-Response-Example' AsynchronousRejectResponseExample: $ref: '#/components/examples/EntityId-Update-Async-Reject-Response-Example' AsynchronousFailureResponseExample: $ref: '#/components/examples/EntityId-Async-Failure-Response-Example' responses: '202': description: Accepted content: application/json: schema: type: object securitySchemes: Client_Credentials: description: '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. ' type: oauth2 flows: clientCredentials: tokenUrl: /authenticationservices/v3/oauth/token