Create a business entity

TxB APIs allow users to create entities (aka onboard new customers) and submit all necessary supporting documentation. Once the entities have been created, you can create accounts, make payments, retrieve reporting, and request FX rates on behalf of the newly created entities. This guide will explain the steps necessary to open a client Entity.

Step by step guide

Step 1 - Create an entity

Firstly, you should send all the necessary client details for the type of business you are onboarding. Specific information per business type will be agreed upfront as part of the onboarding process.

POST /v2/entities/BUSINESS with a representative payload:

{
    "businessEntityRequest": {
        "requestId": "PartnershipClient1",
        "branchCountry": "US",
        "role": "PARTNERSHIP_CLIENT",
        "legalName": "Wayne Enterpises Inc",
        "legalStructure": "CORP",
        "addresses": [
            {
                "addressLines": [
                    "Wayne Tower"
                ],
                "city": "Gotham",
                "postalCode": "GO 10030",
                "countryISOCode": "US",
			“…”
            }
	    ]
    }
}

Once submitted you should receive a 200 okay response detailing the associated entityId.

{
    "message": "8C1BFE0D82374B6DBDDA2617CAD12269"
}

Role Descriptions

Step 2 - Upload necessary documentation

Once the initial entity onboarding request has been submitted you can now send the necessary documentation. To do this you will need to utilize the document APIs.

POST / /v2/documents?purpose=ENTITY_MANAGEMENT:

{
	"customerIdentifier": {
		"entityId": "8C1BFE0D82374B6DBDDA2617CAD12269"
	},
	"documentFile": "assets/documents/ClientXFormationDocument.jpg"
	"documentType": "FORM_990"
}

Once submitted, you should receive a 200 okay response with the following information:

{
    "documentId": "5f3b9999-bb6d-4931-bc81-6ea855eede7b",
    "documentStatus": "ACTIVE",
    "entityId": "8C1BFE0D82374B6DBDDA2617CAD12269",
    "externalSourceId": null,
    "creationTime": "2022-11-23T10:08:37Z",
    "documentName": "Bank Test.png",
    "documentType": "FORM_990",
    "documentTypeOtherDescription": null,
    "uploader": "PARTNER",
    "linkUrl": {
        "linkType": "SELF",
        "linkUrl": "https://api.uat.txb.gs.com/v2/documents/eyJlb...flk8khHgj5YWs/file",
        "method": "GET"
    },
    "relatedCases": null
}

Repeat this step for all necessary documents to be uploaded.

Note: The linkUrl included allows you to re-download the document should you need to. The link is only valid for 5 days after which you will need to query GET/v2/documents/{documentId} in order to receive an updated link.

Step 3 (Optional) – Edit entity payload prior to submission

Prior to submitting the entity and documents for review, you can edit the entity payload. To do this you will need to resend a complete payload including all necessary attributes.

POST /v2/entities/8C1BFE0D82374B6DBDDA2617CAD12269 with a representative payload:

{
    "businessEntityRequest": {
        "requestId": "PartnershipClient1Edit",
        "branchCountry": "US",
        "role": "PARTNERSHIP_CLIENT",
        "legalName": "Wayne Enterpises Inc",
        "legalStructure": "CORP",
        "addresses": [
            {
                "addressLines": [
                    "Wayne Tower"
                ],
                "city": "Gotham",
                "postalCode": "GO 10030",
                "countryISOCode": "US",
			“…”
            }
	    ]
    }
}

Once submitted you should receive a 200 Okay response detailing the associated entityId.

{
    "message": "8C1BFE0D82374B6DBDDA2617CAD12269"
}

The entityId will be the same as the original provided.

Step 4 - Submit entity & documents for review

Once all documents have been uploaded, you can now submit the information for review.

POST /v2/entities/8C1BFE0D82374B6DBDDA2617CAD12269/submit

This will return a 200 okay response.

This will create a task for the TxB operations team who will review the request and supporting documentation. Onboarding checks such as KYC, Compliance and Tax will be conducted at this time and no further changes to your request payload will be possible. If operations identify incorrect or missing information/ documentation, then they will return the onboarding and advise the reason.

Step 5 – Monitor status of onboarding request

You can monitor the status of your onboarding by using the v1 entities API.

GET /v1/entities/entityRequests/8C1BFE0D82374B6DBDDA2617CAD12269 returns:

{
    "entityId": "8C1BFE0D82374B6DBDDA2617CAD12269",
    "message": null,
    "status": "REVIEW"
}

Once the entity onboarding request has been reviewed and fully onboarded then the status will show as “COMPLETED”.

Step 6 – View your entity

Once your entities have been created then you can retrieve the details. If the entity onboarding is not in a “COMPLETED” status then the entity details will not be visible, and you can return to ‘Step 3’ to monitor the status.

GET /v2/entities/8C1BFE0D82374B6DBDDA2617CAD12269 returns:

{
    "entityId": "8C1BFE0D82374B6DBDDA2617CAD12269 ",
    "aliasId": " Wayne Enterpises Inc ",
    "status": "ACTIVE",
    "entityData": {
        "businessEntity": {
            "legalName": " Wayne Enterpises Inc ",
            "legalStructure": "CORP",
            "addresses": […]
		},
		“…”
	},
	“…”
}

Step 7 (Optional) – Retrieve related documents

At any time once the onboarding process has commenced then you can retrieve documents related to an entity. Use the documents API including the query parameter entityId to retrieve a list.

GET /v2/documents?entityId=8C1BFE0D82374B6DBDDA2617CAD12269

{
    "documentList": [
        {
            "documentId": "cbda7bfd-4e82-4cc9-99a7-b8f249d37745",
            "entityId": "64E52BCBF6A247DABA4C7C1E99EAC642",
            "externalSourceId": null,
            "numberOfRelatedCases": null,
            "documentStatus": "DELETED",
            "creationTime": "2022-11-16T14:51:49Z",
            "linkUrl": null
        },
        {
            "documentId": "a560aa14-06e0-491c-b095-b2147744485b",
            "entityId": "64E52BCBF6A247DABA4C7C1E99EAC642",
            "externalSourceId": null,
            "numberOfRelatedCases": null,
            "documentStatus": "ACTIVE",
            "creationTime": "2022-11-16T14:52:44Z",
            "linkUrl": {
                "linkType": "SELF",
                "linkUrl": "https://api.uat.txb.gs.com/v2/documents/eyJl...MdkKPU/file",
            }
        }
    ]
}

Note: The linkUrl included allows you to re-download the document should you need to. The link is only valid for 5 days after which you will need to query repeat this step or move on to step 8

Step 8 (Optional) – Retrieve specific document details

You can also retrieve the details of a document using the documentId

GET /v2/documents/a560aa14-06e0-491c-b095-b2147744485b

{
    "documentId": "a560aa14-06e0-491c-b095-b2147744485b",
    "documentStatus": "ACTIVE",
    "entityId": "64E52BCBF6A247DABA4C7C1E99EAC642",
    "externalSourceId": null,
    "creationTime": "2022-11-16T14:52:44Z",
    "documentName": "Bank Test.png",
    "documentType": "FORM_990",
    "documentTypeOtherDescription": null,
    "uploader": "PARTNER",
    "linkUrl": {
        "linkType": "SELF",
        "linkUrl": "https://api.uat.txb.gs.com/v2/documents/eyJlbm...ygc_E/file",
        "method": "GET"
    },
    "relatedCases": null
}