Rapyd Verify API

Easily collect business details to verify your users. | Enterprise beta

Rapyd conducts it’s due diligence to inspect the KYB of a business. You can use Rapyd Verify to collect details of a business to be verified. Rapyd’s APIs work together to evaluate the seller’s application, and at the end of the process, sends an approval or a rejection. Once a business of a seller is approved, Rapyd updates the platform capabilities and the available transactions that can be processed.

Common Use Cases

  • A client uses the Rapyd Verify API to create a white-labled application to onboard their business users.
  • A client uses the Rapyd Verify API to approve sellers on their marketplace platform before selling.

Rapyd Verify Workflow

Step 1: Find Applications for Country

2064
  1. Seller asks you for available application types. This is done by the seller
    selecting an application type from a drop-down list on the client's site hosted solution.
  2. You use List Application Types by Country to find available application types in a country.
  3. Rapyd responds with a list of application types for the specified country.
  4. You display a list of application types to the seller.

Step 2: Create Application

2064
  1. Seller fills out the form on your site for retrieving an application.
  2. You use the Create Application call to create the application type.
  3. Rapyd sends the application to you.
  4. You display the application to the seller.

Step 3: Fill Out Application and Save

2064
  1. Seller fills out an application on your site and saves it.
  2. You use Save Application to save the seller’s application.
  3. Rapyd returns the saved application and increments the application version by 1.
  4. You display the saved form data to be filled out by the seller.

Note: Steps 1-4 are done again until all the required fields in the application are completed.

Step 4: Upload Application Documents

2064

One or more mandatory fields in the application include a requirement for uploading a document.

  1. Hosted solution of client asks seller for more documents such as identification papers.
  2. Seller uploads documents via the client’s hosted solution.
  3. You use Upload Document to upload the documents to Rapyd.

Step 5: Add Sections to Application

2064

This step is done in a scenario where a company structure includes owner of owners (sub-owners). A structure, similar to a hierarchical tree where a company owner can, in turn be owned by another company.

  1. Seller indicates the number of co-owners in the company.
  2. You use Add Subsection to add an owner section to the application.
  3. Rapyd sends the revised application to you.
  4. You display the application to the seller.

Step 6: Submit Application

2064
  1. Seller fills out all mandatory fields of application form, and submits application on your site.
  2. You use Submit Application to submit the seller’s application to Rapyd.
  3. Rapyd manually reviews the submitted application. It may ask for more information/documents. Rapyd then sends an approval/rejection message of the submitted application to you.
  4. You display the approval/rejection message on the application to the seller.

How It Works

Step 1: Get Applications for Country Request

The client asks Rapyd for the list of application types in the US. For this use case, the client uses the ‘Get applications for country’ method with the following parameters:

Query ParameterDescription
countryEnter US as the country code for the United
States.

Get Applications for Country Request

GET https://sandboxapi.rapyd.net/v1/verify/applications/types/country/US

Get Applications for Country Response

Let's take a look at the 'GET applications for country' response.

{
"status": {
"error_code": "",
"status": "SUCCESS",
"message": "",
"response_code": "",
"operation_id": "0b8f0683-ab5e-4dc4-a466-44f003faf493"
},
"data": [
{
"application_type_cd": "us_company",
"entity_type": "Company",
"country_iso_2": "US"
},
{
"application_type_cd": "us_non_profit",
"entity_type": "Non-profit",
"country_iso_2": "US"
}
  • The data section of this response shows that us_company is an acceptable application type in the United States. Since the entity type is a company, the user will ask for an application type of a ‘us_company’.

Step 2: Create Application

The ‘Create application’ method with the following parameters:

Body ParameterDescription
rapyd_entity_tokenEnter the Rapyd Wallet of the seller. In this
use case
ewallet_956bdb9bfd9e9e45a39d804e70ade043 is used as the ewallet.
application_type_cdEnter us_company as the type of
application
client_reference_idEnter 000003111 as the reference number
for the Seller.
authorized_user_emailEnter [email protected] as the seller’s
email address.
metadataEnter {"merchant_defined":"True"}

Create Application Request

Client asks Rapyd for the us_company application.

Request URL POST https://sandboxapi.rapyd.net/v1/verify/applications/
{
"rapyd_entity_token" : "ewallet_956bdb9bfd9e9e45a39d804e70ade043",
"application_type_cd" : "us_company",
"client_reference_id": "000003111",
"authorized_user_email": "[email protected]",
"metadata": {
"merchant_defined":"true"
}
}

Create Application Response

Let's take a look at the ‘Create application' response.

Response
{
"status": {
"error_code": "",
"status": "SUCCESS",
"message": "",
"response_code": "",
"operation_id": "b36695ba-91ee-4285-a7fa-2a7eb1d6d37f"
},
"data": {
"token": "app_593967c6-d04e-4d49-9823-e7723046fa7c",
"rapyd_entity_token": "ewallet_956bdb9bfd9e9e45a39d804e70ade043",
"client_reference_id": "000003111",
"application_type_token": "appt_b0ec345b-d592-4970-bfd4-b3637f5e841d",
"authorized_user_email": "[email protected]",
"version": 0,
"status": "new",
"comments": null,
"metadata": {
"Client_defined": "True"
},
"entity_type": "Company",
"country_iso_2": "US",
"Sections":{
// . . .
},
"created_at": 1614069071558,
"updated_at": 1614069071558,
"application_type_cd": "us_company"
}
}

Note: Portions of the response have been omitted since the original request includes many lines.

The data section of this response shows that the ‘token’ for this application is app_593967c6-d04e-4d49-9823-e7723046fa7c. This value will be used in the later API calls for saving and submitting the application.

Step 3: Fill out Application and Save

1543
Query ParameterDescription
tokenEnter
app_593967c6-d04e-4d49-9823-e7723046
fa7c
as the token for the application.
actionEnter save as the type of action

The client copies and pastes the entire ‘sections’ object of the response in step 2 to the body of the request.

Post Save/Submit Application Request

Client asks Rapyd to save an application with the token app_593967c6-d04e-4d49-9823-e7723046fa7c.

Request URL POST https://sandboxapi.rapyd.net/v1/verify/applications/app_593967c6-d04e-4d49-9823-e7723046fa7c/save/

{
"sections": {
"company": [
{
"token": "sect_0f82a783-d5d4-4efb-95ec-5d8149ed43be",
"original_token": "sct_sdf98e0011",
"name": "Company",
"description": null,
"comments": null,
"section_type": "company",
"is_valid": null,
"reject_reason": null,
"is_multiple": false,
"sort_order": 1,
"max_instances": 1,
"allow_children": false,
"max_children": 0,
"validation": null,
"data_elements": [
{
"token": "elem_837f7a25-aca4-4529-b392-c0bcced4aed5",
"original_token": "elm_up098e0014",
"name": "Name",
"description": "",
"comments": null,
"is_mandatory": true,
"is_valid": true,
"reject_reason": null,
"sort_order": 1,
"fields": [
{
"token":
"fld_b5b5f581-2866-4eb8-b9ea-d40a99cebef0",
"value": null,
"original_token": "fld_up098e0014",
"type": "",
"name": "name",
"description": "Full name of the business.",
"comments": null,
"input_type": "input",
"is_mandatory": true,
"input_validation": {},
"sort_order": 1,
"is_valid": true,
"reject_reason": "",
"sub_type": null,
"files": [],
"is_read_only": false,
"LOV": [],
"created_at": null,
"updated_at": null
}
]
},
// ...
}
}

Note: Portions of the request have been omitted since the original request includes many lines.

Save/Submit Application Response

Let's take a look at the 'POST Create application' response.

{
"status": {
"error_code": "",
"status": "SUCCESS",
"message": "",
"response_code": "",
"operation_id": "e1a2425b-30b7-43e6-b1b9-9df53a81ec03"
},
"data": {
"token": "app_593967c6-d04e-4d49-9823-e7723046fa7c",
"rapyd_entity_token": "ewallet_956bdb9bfd9e9e45a39d804e70ade043",
"client_reference_id": "000001111",
"application_type_token": "appt_21fcb515-1694-4986-8be2-447a2fc82de0",
"authorized_user_email": "[email protected]",
"version": 1,
"status": "new",
"comments": null,
"metadata": {
"Client defined": "True"
},
"entity_type": "Company",
"country_iso_2": "US",
}

Note: Portions of the response have been omitted since the original request includes many lines.

The data section of this response shows that the ‘version’ for this application is 1.

The ‘sections’ object of the response is displayed by the client as a form to the seller. The seller enters a field in the form and then saves the form.

The client inserts the ‘sections’ object of the response to the body of the next request, and the following update is done in the ‘fields’ object: * The value is updated from null to "value": "Acme music streaming".

"fields": [
{
"token":
"fld_b5b5f581-2866-4eb8-b9ea-d40a99cebe
f0",
"value": "Acme music streaming",
"original_token": "fld_up098e0014",
"type": "",
"name": "name",
"description": "Full name of the
business.",
"comments": null,
"input_type": "input",
"is_mandatory": true,
"input_validation": {},
"sort_order": 1,
"is_valid": true,
"reject_reason": "Field 'name' - should
not be empty or null",
"sub_type": null,
"files": [],
"is_read_only": false,
"LOV": [],
"created_at": null,
"updated_at": null
}
1380

Client asks Rapyd to save an application with the token app_593967c6-d04e-4d49-9823 e7723046fa7c and the name Acme music streaming as the value in the ‘name’ field.

Request URL

POST https://sandboxapi.rapyd.net/v1/verify/applications/app_593967c6-d04e-4d49-9823-e7723046fa7c/save/
{
"sections": {
"company": [
{
"token": "sect_0f82a783-d5d4-4efb-95ec-5d8149ed43be",
"original_token": "sct_sdf98e0011",
"name": "Company",
"description": null,
"comments": null,
"section_type": "company",
"is_valid": false,
"reject_reason": "elem_837f7a25-aca4-4529-b392-c0bcced4aed5,
elem_2c8941e6-c551-4f3a-9206-b5d585f3a1f8,
elem_4b45a982-67fd-4b28-bc08-34972f3a433b,
elem_d4a0dd13-80d4-45b5-b3cc-c19e1a4da585,
elem_be89e86b-8066-4dc9-b054-2f0308947812",
"is_multiple": false,
"sort_order": 1,
"max_instances": 1,
"allow_children": false,
"max_children": 0,
  "data_elements": [
{
"token": "elem_837f7a25-aca4-4529-b392-c0bcced4aed5",
"original_token": "elm_up098e0014",
"name": "Name",
"description": "",
"comments": null,
"is_mandatory": true,
"is_valid": false,
"reject_reason":
"fld_b5b5f581-2866-4eb8-b9ea-d40a99cebef0",
"sort_order": 1,
"fields": [
{
"token":
"fld_b5b5f581-2866-4eb8-b9ea-d40a99cebef0",
"value": "Acme music streaming",
"original_token": "fld_up098e0014",
"type": "",
"name": "name",
"description": "Full name of the business.",
"comments": null,
"input_type": "input",
"is_mandatory": true,
"input_validation": {},
"sort_order": 1,
"is_valid": true,
"reject_reason": "Field 'name' - should not be
empty or null",
"sub_type": null,
"files": [],
"is_read_only": false,
"LOV": [],
"created_at": null,
"updated_at": null
}
]
}
// ...
"created_at": 1614069071558,
"updated_at": 1614069599525,
"application_type_cd": "us_company_test"
}

Note: Portions of the request have been omitted since the original request includes many lines.

Save/Submit Application Response Version 2

Response

{
"status": {
  "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "66547b0f-b2ce-46bd-9458-84606b317f70"
},
"data": {
  "token": "app_593967c6-d04e-4d49-9823-e7723046fa7c",
  "rapyd_entity_token": "ewallet_956bdb9bfd9e9e45a39d804e70ade043",
  "client_reference_id": "000003111",
  "application_type_token": "appt_b0ec345b-d592-4970-bfd4-b3637f5e841d",
  "authorized_user_email": "[email protected]",
  "version": 2,
  "status": "new",
  "comments": null,
"metadata": {
    "Client defined": "True"
},
"entity_type": "Company",
"country_iso_2": "US",
"sections": {
"company": [
{
  "token": "sect_0f82a783-d5d4-4efb-95ec-5d8149ed43be",
  "original_token": "sct_sdf98e0011",
  "name": "Company",
  "description": null,
  "comments": null,
  "section_type": "company",
  "is_valid": false,
  "reject_reason": "elem_2c8941e6-c551-4f3a-9206-b5d585f3a1f8,
  elem_4b45a982-67fd-4b28-bc08-34972f3a433b,
  elem_d4a0dd13-80d4-45b5-b3cc-c19e1a4da585,
  elem_be89e86b-8066-4dc9-b054-2f0308947812",
  "is_multiple": false,
  "sort_order": 1,
  "max_instances": 1,
  "allow_children": false,
  "max_children": 0,
  "validation": null,
"data_elements": [
{
  "token": "elem_837f7a25-aca4-4529-b392-c0bcced4aed5",
  "original_token": "elm_up098e0014",
  "name": "Name",
  "description": "",
  "comments": null,
  "is_mandatory": true,
  "is_valid": true,
  "reject_reason": "",
  "sort_order": 1,
"fields": [
{
  "token":
  "fld_b5b5f581-2866-4eb8-b9ea-d40a99cebef0",
  "value": "Acme music streaming",
  "original_token": "fld_up098e0014",
  "type": "",
  "name": "name",
  "description": "Full name of the business.",
  "comments": null,
  "input_type": "input",
  "is_mandatory": true,
  "input_validation": {},
  "sort_order": 1,
  "is_valid": true,
  "reject_reason": "",
  "sub_type": null,
  "files": [],
  "is_read_only": false,
  "LOV": [],
  "created_at": null,
  "updated_at": null
}
]
},
// ...
},
"created_at": 1614069071558,
"updated_at": 1614070309193,
"application_type_cd": "us_company"
}
}

Note: Portions of the request have been omitted since the original request includes many lines.

The data section of this response shows that the version for this application is 2. The
name field includes the value Acme music service.

The updated ‘sections’ object is displayed by the client as a form to the seller.

The seller enters more fields in the form and then saves the form. The client copies the sections object of the response and pastes it to the body of the next request. The relevant fields in the body of the request are updated and it runs in the same fashion that was described in the previous section. The response then indicates that the version for this application is 3.

This process is continued until all the mandatory fields in the form are completely filled out. When the form is filled out, the client runs the Post Save/Submit application with the action set to submit (see Step 6).

Step 4: Upload Application Documents

One or more mandatory fields include a requirement for uploading a document.
The client asks Rapyd to upload a document by using the ‘Upload application documents’ method with the following parameters:

Path ParameterDescription
application_tokenEnter app_593967c6-d04e-4d49-9823-e7723046fa7c as the token for the application to upload a document.
section_tokenEnter sect_0f82a783-d5d4-4efb-95ec-5d8149ed43be as the section of the application that requires to upload a document.
field_tokenEnter fld_b5b5f581-2866-4eb8-b9ea-d40a99cebef0 as the field in the section of the
application that requires uploading a document.
original_file_nameUse the name of the file that is being uploaded. The file must be in PNG format. Enter id_1.png as the name of the file.
fileEnter the base64 encoded string of the image. Enter iVBORw. Since this string is very long, the example includes only its initial characters.

Upload Application Document Request

Client asks Rapyd to upload a document for the application.

POST https://sandboxapi.rapyd.net/v1/verify/applications/documents/app_593967c6-d04e-4d49-982
3-e7723046fa7c/sect_0f82a783-d5d4-4efb-95ec-5d8149ed43be/fld_b5b5f581-2866-4e
b8-b9ea-d40a99cebef0
{
"original_file_name": "id_1.png",
"file": "iVBORw"
}

Upload Application Document Response

{
"status": {
"error_code": "",
"status": "SUCCESS",
"message": "",
"response_code": "",
"operation_id": "2403c3ed-82e7-48fc-ac15-9bf62ef9d389"
}
}

The response shows that a document has been uploaded to the application.

Note: The client must run the ‘Save/Submit application’ method in step 3 in order to save this image to the application. After saving the application, the uploaded file will include its own file ID that starts with file_ (token) as demonstrated in the following portion of the save application response.

Response for Saved File

{
// ...
"files": [
{
"token": "file_5509b9b4-fded-4410-ae21-555213b5f14e",
"type": "image/png",
"url": "9841d360-edb0-44f6-ac4d-d3ca7adc8888_ttt.png",
"origin_name": "id_1.png",
"is_deleted": false
}
],
// ....
}

The client can remove a document that has been previously uploaded and saved. For this use case, the client can run the ‘Delete application document’ method with the following parameters:

Body ParameterDescription
application_tokenEnter app_593967c6-d04e-4d49-9823-e7723046fa7c as the token for the application to upload a document.
section_tokenEnter sect_0f82a783-d5d4-4efb-95ec-5d8149ed43be as the section of the application that requires uploading a document.
field_tokenEnter fld_b5b5f581-2866-4eb8-b9ea-d40a99cebef0 as the field in the section of the
application that requires uploading a document.
file_tokenEnter file_5509b9b4-fded-4410-ae21-555213b5f14e as the ID of the file that is provided after the application is saved,

Delete Application Document Request

Client asks Rapyd to delete a file from the application.

DELETE https://sandboxapi.rapyd.net/v1/verify/applications/documents
{
"application_token": "app_42349ff8-405d-4102-9bc7-35a92c91b7bf",
"section_token": "sect_0f82a783-d5d4-4efb-95ec-5d8149ed43be",
"field_token": "fld_b5b5f581-2866-4eb8-b9ea-d40a99cebef0",
"file_token": "file_5509b9b4-fded-4410-ae21-555213b5f14e"
}

Delete Application Document Response

{
"status": {
"error_code": "",
"status": "SUCCESS",
"message": "",
"response_code": "",
"operation_id": "5a118b65-5adf-48ed-99d1-9b1d9bd6cab5"
}
}

The response shows that the file has been deleted in the application.

Note: You must also run the ‘Save/Submit application’ method in step 3 to remove the file from the application.

Step 5: Add Sections to Application

This step is done when a company can be owned by another company. Additional sub owners can be added by running the Add subsection block method with the following parameters:

Path ParameterDescription
tokenEnter app_593967c6-d04e-4d49-9823-e7723046fa7c as the token for the application.
sectionEnter sect_0f82a783-d5d4-4efb-95ec-5d8149ed43be as the owner section in the application that needs to be duplicated.

Add Subsection Block Request

Client asks Rapyd to add an owner section to the seller’s application.

POST https://sandboxapi.rapyd.net/v1/verify/applications/app_593967c6-d04e-4d49-9823-e7723046fa7c/section/sect_0f82a783-d
5d4-4efb-95ec-5d8149ed43be

Add Subsection Block Response

{
"status": {
  "error_code": "",
  "status": "SUCCESS",
  "message": "",
  "response_code": "",
  "operation_id": "0627523f-c016-4503-92bd-4fd68f7cad6d"
},
"data": {
  "token": "sect_0f82a783-d5d4-4efb-95ec-5d8149ed43be",
  "original_token": "sct_sdf98e0013",
  "name": "Owner",
  "description": null,
  "comments": null,
  "section_type": "owner",
  "is_valid": null,
  "reject_reason": null,
  "is_multiple": true,
  "sort_order": 1,
  "max_instances": 4,
  "allow_children": true,
  "max_children": 4,
  "validation": {
  "method": "ignore_if_field_empty",
  "element_id": "elm_up098e0028",
  "field_id": "fld_up098e0039"
},
// . . .
"child_sections": [
{
  "token": "",
  "original_token": "sct_sdf98e0013",
  "name": "Owner",
  "description": null,
  "comments": null,
  "section_type": "owner",
  "is_valid": null,
  "reject_reason": null,
  "is_multiple": true,
  "sort_order": 1,
  "max_instances": 4,
  "allow_children": true,
    "max_children": 4,
  "validation": {
  "method": "ignore_if_field_empty",
  "element_id": "elm_up098e0028",
  "field_id": "fld_up098e0039"
},
// . . .
}

Note: Portions of the request have been omitted since the original request includes many lines.

The child_sections section of this response shows that a sub-owner section has been
added to the application, and that the additional owner of the business will be able to fill out the application in the new section after the application is saved via the ‘Save/Submit Application’ method (step 3).

Note: After saving this application the new owner section will include its own ID that starts with the sect_ (token).

The client can remove a sub-owner section that has been previously added and saved by running the ‘Delete subsection block’ method.

Step 6: Submit Application

Note: Mandatory fields are indicated by the ‘is_mandatory’ field.

The client uses the ‘Save/Submit application’ method with the following parameters:

Query ParameterDescription
tokenEnter app_593967c6-d04e-4d49-9823-e7723046fa7c as the token for the application.
actionEnter submit as the type of action

For the body of the request, the client uses the ‘sections’ object of the latest ‘Save/Submit application’ response and updates all the mandatory field values.

Note: When the form is submitted, it can no longer be edited.

Save/Submit Application Request

Client asks Rapyd to submit an application with the token app_593967c6-d04e-4d49-9823-e7723046fa7c .

POST https://sandboxapi.rapyd.net/v1/verify/applications/app_593967c6-d04e-4d49-9823-e7723046fa7c/submit/
{
"sections": {
  "company": [
  {
    "token": "sect_0f82a783-d5d4-4efb-95ec-5d8149ed43be",
    "original_token": "sct_sdf98e0011",
    "name": "Company",
    "description": null,
    "comments": null,
    "section_type": "company",
    "is_valid": false,
    "reject_reason": "elem_2c8941e6-c551-4f3a-9206-b5d585f3a1f8,
    elem_4b45a982-67fd-4b28-bc08-34972f3a433b,
    elem_d4a0dd13-80d4-45b5-b3cc-c19e1a4da585,
    elem_be89e86b-8066-4dc9-b054-2f0308947812",
    "is_multiple": false,
    "sort_order": 1,
    "max_instances": 1,
    "allow_children": false,
    "max_children": 0,
    "validation": null,
    "data_elements":
    // ...
      "fields": [
    // ...
    ]
    "child_sections": [
    // ...
    ]
    }
  ]
  }
}

Note: Portions of the request have been omitted since the original request includes many lines.

Post Save/Submit Application Response

{
"status": {
  "error_code": "",
  "status": "SUCCESS",
  "message": "",
  "response_code": "",
  "operation_id": "a519aaa8-52fe-4112-93f1-6ef099902c08"
},
"data": {
  "token": "app_593967c6-d04e-4d49-9823-e7723046fa7c",
  "rapyd_entity_token": "ewallet_956bdb9bfd9e9e45a39d804e70ade043",
  "client_reference_id": "000003111",
  "application_type_token": "appt_b0ec345b-d592-4970-bfd4-b3637f5e841d",
  "authorized_user_email": "[email protected]",
  "version": 6,
  "status": "new",
  "comments": null,
"metadata": {
    "Client defined": "True"
},
  "entity_type": "Company",
  "country_iso_2": "US",
"sections": {
    "company": [
{
  "token": "sect_0f82a783-d5d4-4efb-95ec-5d8149ed43be",
  "original_token": "sct_sdf98e0011",
    "name": "Company",
  "description": null,
  "comments": null,
  "section_type": "company",
  "is_valid": false,
  "reject_reason": "elem_2c8941e6-c551-4f3a-9206-b5d585f3a1f8,
  elem_be89e86b-8066-4dc9-b054-2f0308947812",
  "is_multiple": false,
  "sort_order": 1,
  "max_instances": 1,
  "allow_children": false,
  "max_children": 0,
  "validation": null,
"data_elements": [
{
  "token": "elem_837f7a25-aca4-4529-b392-c0bcced4aed5",
  "original_token": "elm_up098e0014",
  "name": "Name",
  "description": "",
  "comments": null,
  "is_mandatory": true,
  "is_valid": true,
  "reject_reason": "",
  "sort_order": 1,
  "fields": [
  // ...
  ]
  "child_sections": [
  // ...
  ]
 }
  ]
},
"created_at": 1614069071558,
"updated_at": 1614071990680,
"application_type_cd": "us_company"
}
}

Note: Portions of the response have been omitted since the original request includes many lines.

The data section of the response indicates that the current version of the application is 6. This value indicates that the application has been saved 5 times and at the 6th time was saved and submitted.

At this phase, Rapyd manually inspects the data in the form, and at the end of the review process rejects or approves the application of the seller. The status of the application is then sent to the client, and the client displays the rejection/approval of the application to the seller.

In case of a rejection, there may be circumstances where the reason for the rejection is also provided, and the seller may have the option to supply more information or documents to the client in order to get an approval.

Updated about a year ago

Rapyd Verify API


Easily collect business details to verify your users. | Enterprise beta

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.