Skip to main content
An identity is a core object in our API, representing the fundamental information required for any individual or business to interact with partner financial institutions (PFIs) via the Borderless network. All transactions, payment instructions, and accounts are associated with an identity. All identities must pass a compliance check before they are allowed to do any transactions in the network. The compliance check can be performed by you or the (PFI), depending on the compliance model that the PFI supports. You can find more detailed information in the compliance section below.
If you’re just getting started, please check out our quick start guide.

​
Identity types

There are two types of identities in the Borderless network: Personal — used to represent a person. Can usually start doing transactions on the Borderless network in minutes. You can find detailed instructions on how to create them and get them ready in the Personal Identity tab below. Business — used to represent a business or corporation. Can usually start doing transactions on the Borderless network in three to five business days. You can find detailed instructions on how to create these identities and get them ready in the Business Identity tab below.

​
Compliance details

Each Partner Financial Institution (PFI) on the Borderless network has its own compliance programs, and decides how to implement them. The Borderless network is a data layer that stores the information for every person or business doing transactions, and sends it on to the PFIs for their usual operations and record keeping. You only upload the necessary data to the Borderless identity once, then it is available for all the PFIs in the network. This is is part of a process called compliance orchestration. In some cases, passing one compliance-check will automatically satisfy other checks with less strict requirements. This is handled via the incorporates field: [slug-1, slug-2] This means that upon passing this compliance-check, the identity also gains access to the operation options covered by the checks listed in incorporates.
Compliance Check Flow

​
Working with identities & compliance

Note: Borderless is never in the flow of funds, and never takes custody of client or partner funds. Borderless is a gateway connecting clients directly with regulated and licensed providers.
  • Personal Identity
  • Business Identity

​
Create a personal identity

Creating a personal identity is an important step when using the Borderless network. Every deposit or withdrawal must be tied to an identity, and this is also how we collect information for required compliance checks (KYC).

​
Step 1: Initiate identity object

First, initiate an identity object, which creates a simple identity object. We will then add information to this object so that we can use it for KYC or KYB going forward. You can find a link to the endpoint reference documentation, as well as request and response examples below.This compliance process is managed by our partner finanical institutions (PFIs) who are the locally licensed and regulated stablecoin and fiat on-ramps and off-ramps.Some requests require an Idempotency-Key header to ensure that operations are not accidentally executed multiple times. Please generate and use a unique UUID for this field.
Please capture identity id from the response to use it during account creation later.
Endpoint: POST /identities/personal
curl -X POST "https://sandbox-api.borderless.xyz/v1/identities/personal" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
     -d '{
  		"firstName": "John",
  		"lastName": "Doe",
  		"secondLastName": "Smith",
  		"middleName": "Michael",
  		"taxId": "123456789",
  		"dateOfBirth": "2003-01-01",
  		"email": "john.doe@example.com",
  		"phone": "+1234567890",
  		"activity": "Software Engineer",
  		"sex": "Male",
  		"occupationCode": "172011",
  		"employmentStatus": "SelfEmployed",
  		"sourceOfFunds": "InvestmentsLoans",
  		"accountPurpose": "InvestmentPurposes",
  		"accountPurposeOther": "string",
  		"monthlyAmounts": "From10KTo50K",
  		"actingAsIntermediary": false,
  		"address": {
   		 	"street1": "123 Main St",
    		"street2": "Apt 4B",
    		"city": "New York",
    		"state": "NY",
    		"country": "US",
    		"postalCode": "10001"
  			}
		}
		'

​
Step 2: Gather configured PFIs

Once an identity has been created, this identity will have limited ability to transact until they pass a KYC or KYB check with the on-ramp and off-ramp providers (PFIs) they’d like to enable. You can easily gather the configured PFIs from our API before collecting the necessary documents and initiating a compliance check.Additionally, this endpoint provides the terms of service link, where required, which will need to be forwarded to the client. Some of our partner financial institutions (PFIs) require users to accept their terms and conditions before they can transact. Each identity must accept their own ToS link, and it cannot be reused.
Please capture compliance slug from the response to use it next.
Please capture terms of service link to deliver to end users.
Endpoint: GET /identities/{identityId}/compliance-checks
curl -X GET "https://sandbox-api.borderless.xyz/v1/identities/{identityId}/compliance-checks" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -d '{
            "country": "AF",
            "asset": "USDC_BASE",
            "fiat": "USD", 
            "paymentMethod": "ACH",
            "type": "Deposit"
         }'

​
Step 3: Check required documents

With the identity id and compliance slug you can now check the list of required information and documentation needed for the configured PFIs. This allows you to dynamically build your UI such that you only ask your customers for what is required for each specific business or user.
Please use the compliance slug from the response above.
Endpoint: GET /identities/{identityId}/compliance-checks/{slug}/requirements
curl -X GET "https://sandbox-api.borderless.xyz/v1/identities/{identityId}/compliance-checks/{slug}/requirements" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \

​
Step 4: Attach required documents

Now that required documents have been identified, and the terms of service link, if required, has been accepted, we can submit these documents for review via our API. This information will be added to the identity object so that we can streamline and orchestrate future compliance as well.For clarity, the id parameter here is the identity id of the organization or person you have created in step 1 of this process. This will submit all required information for the compliance check. You can use this endpoint at any time to add documents to the related identity object.
Please note, imageFront and imageBack should be converted in base64 format with resolution at least 200*200pixels.
Endpoint: PUT /identities/{id}/documents
curl -X PUT "https://sandbox-api.borderless.xyz/v1/identities/{id}/documents" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
     -d '{
            "issuingCountry": "US",
            "type": "Passport",
            "issuedDate": "2024-07-25",
            "expiryDate": "2027-07-25",
            "imageFront": "image/200*200;base64",
            "imageBack": "image/200*200;base64"
         }'

​
Step 5: Start compliance check

After attaching the required documents to the identity object, you are ready to submit and start the compliance check with our partner financial institutions (PFIs). You can submit this once, and we will orchestrate the data to all PFIs you have enabled, helping to streamline an otherwise repetitive process.If all prerequisites are satisfied, the check will begin. Use the GET request above from step 2 and the API will return the current compliance status.
Endpoint: POST /identities/{identityId}/compliance-checks/{slug}
curl -X POST "https://sandbox-api.borderless.xyz/v1/identities/{identityId}/compliance-checks/{slug}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
The timeline for different levels of compliance checks varries. It can be as fast as near-instant and in some rare occasions can take a few days. We will keep you informed through the whole process via the returned compliance status in the response body of step 2.
Requests for information (RFIs) are a regular part of the compliance process. If there are follow up questions on documents, completely missing documents, or other details that need to be reviewed manually, our PFIs can send a request for additional information.
These requests for information will be communicated manually, and are generally expected to be resolved in 24 to 48 hours.
If you have any questions, please don’t hesitate to reach out to us via email or slack.