Attach Documents to Individual Customer
curl --request POST \
--url https://sandbox.api.engagexpay.com/v2/customers/{customer_id}/individual/attach \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"identifying_documents": [
{
"type": "SELFIE",
"files": [
{
"uri": "/AbAcQ4hn_0652746727637.pdf"
}
]
},
{
"type": "DRIVERS_LICENSE",
"number": "DL987654321",
"country": "USA",
"state": "US-CA",
"issue_date": "2019-06-01",
"expiry_date": "2029-06-01",
"files": [
{
"side": "FRONT",
"uri": "/AbAcQ4hn_0652746727638.pdf"
},
{
"side": "BACK",
"uri": "/XyZ123mn_0652746727639.pdf"
}
]
}
],
"address_documents": [
{
"type": "BANK_STATEMENT",
"country": "USA",
"files": [
{
"uri": "/PoAdef45_0652746727640.pdf"
}
]
}
],
"tos_policies_value": "e9414388-fbdf-4407-b5c2-bc39eae3645b"
}
'const url = 'https://sandbox.api.engagexpay.com/v2/customers/{customer_id}/individual/attach';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
identifying_documents: [
{type: 'SELFIE', files: [{uri: '/AbAcQ4hn_0652746727637.pdf'}]},
{
type: 'DRIVERS_LICENSE',
number: 'DL987654321',
country: 'USA',
state: 'US-CA',
issue_date: '2019-06-01',
expiry_date: '2029-06-01',
files: [
{side: 'FRONT', uri: '/AbAcQ4hn_0652746727638.pdf'},
{side: 'BACK', uri: '/XyZ123mn_0652746727639.pdf'}
]
}
],
address_documents: [
{
type: 'BANK_STATEMENT',
country: 'USA',
files: [{uri: '/PoAdef45_0652746727640.pdf'}]
}
],
tos_policies_value: 'e9414388-fbdf-4407-b5c2-bc39eae3645b'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://sandbox.api.engagexpay.com/v2/customers/{customer_id}/individual/attach")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"identifying_documents\": [\n {\n \"type\": \"SELFIE\",\n \"files\": [\n {\n \"uri\": \"/AbAcQ4hn_0652746727637.pdf\"\n }\n ]\n },\n {\n \"type\": \"DRIVERS_LICENSE\",\n \"number\": \"DL987654321\",\n \"country\": \"USA\",\n \"state\": \"US-CA\",\n \"issue_date\": \"2019-06-01\",\n \"expiry_date\": \"2029-06-01\",\n \"files\": [\n {\n \"side\": \"FRONT\",\n \"uri\": \"/AbAcQ4hn_0652746727638.pdf\"\n },\n {\n \"side\": \"BACK\",\n \"uri\": \"/XyZ123mn_0652746727639.pdf\"\n }\n ]\n }\n ],\n \"address_documents\": [\n {\n \"type\": \"BANK_STATEMENT\",\n \"country\": \"USA\",\n \"files\": [\n {\n \"uri\": \"/PoAdef45_0652746727640.pdf\"\n }\n ]\n }\n ],\n \"tos_policies_value\": \"e9414388-fbdf-4407-b5c2-bc39eae3645b\"\n}")
.asString();import requests
url = "https://sandbox.api.engagexpay.com/v2/customers/{customer_id}/individual/attach"
payload = {
"identifying_documents": [
{
"type": "SELFIE",
"files": [{ "uri": "/AbAcQ4hn_0652746727637.pdf" }]
},
{
"type": "DRIVERS_LICENSE",
"number": "DL987654321",
"country": "USA",
"state": "US-CA",
"issue_date": "2019-06-01",
"expiry_date": "2029-06-01",
"files": [
{
"side": "FRONT",
"uri": "/AbAcQ4hn_0652746727638.pdf"
},
{
"side": "BACK",
"uri": "/XyZ123mn_0652746727639.pdf"
}
]
}
],
"address_documents": [
{
"type": "BANK_STATEMENT",
"country": "USA",
"files": [{ "uri": "/PoAdef45_0652746727640.pdf" }]
}
],
"tos_policies_value": "e9414388-fbdf-4407-b5c2-bc39eae3645b"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.api.engagexpay.com/v2/customers/{customer_id}/individual/attach"
payload := strings.NewReader("{\n \"identifying_documents\": [\n {\n \"type\": \"SELFIE\",\n \"files\": [\n {\n \"uri\": \"/AbAcQ4hn_0652746727637.pdf\"\n }\n ]\n },\n {\n \"type\": \"DRIVERS_LICENSE\",\n \"number\": \"DL987654321\",\n \"country\": \"USA\",\n \"state\": \"US-CA\",\n \"issue_date\": \"2019-06-01\",\n \"expiry_date\": \"2029-06-01\",\n \"files\": [\n {\n \"side\": \"FRONT\",\n \"uri\": \"/AbAcQ4hn_0652746727638.pdf\"\n },\n {\n \"side\": \"BACK\",\n \"uri\": \"/XyZ123mn_0652746727639.pdf\"\n }\n ]\n }\n ],\n \"address_documents\": [\n {\n \"type\": \"BANK_STATEMENT\",\n \"country\": \"USA\",\n \"files\": [\n {\n \"uri\": \"/PoAdef45_0652746727640.pdf\"\n }\n ]\n }\n ],\n \"tos_policies_value\": \"e9414388-fbdf-4407-b5c2-bc39eae3645b\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"data": {
"customer_id": "55bd6b4e-c20a-4cc8-9535-91d5557a67d9"
},
"meta": null
}{
"status": 400,
"message": "Malformed request body"
}{
"message": "Authentication failed"
}{
"error": {
"code": "forbidden",
"message": "Customer is not eligible for this operation"
}
}{
"message": "Resource not found"
}{
"error": {
"code": "conflict",
"message": "An attach request is already in progress for this customer"
}
}{
"message": "<string>",
"errors": [
{}
]
}{
"status": 500,
"message": "Internal server error"
}Create Individual Customer
Attach Documents to Individual Customer
Attach identifying and address documents to an existing individual customer, using separate identifying_documents and address_documents arrays. Documents are processed asynchronously.
POST
/
v2
/
customers
/
{customer_id}
/
individual
/
attach
Attach Documents to Individual Customer
curl --request POST \
--url https://sandbox.api.engagexpay.com/v2/customers/{customer_id}/individual/attach \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"identifying_documents": [
{
"type": "SELFIE",
"files": [
{
"uri": "/AbAcQ4hn_0652746727637.pdf"
}
]
},
{
"type": "DRIVERS_LICENSE",
"number": "DL987654321",
"country": "USA",
"state": "US-CA",
"issue_date": "2019-06-01",
"expiry_date": "2029-06-01",
"files": [
{
"side": "FRONT",
"uri": "/AbAcQ4hn_0652746727638.pdf"
},
{
"side": "BACK",
"uri": "/XyZ123mn_0652746727639.pdf"
}
]
}
],
"address_documents": [
{
"type": "BANK_STATEMENT",
"country": "USA",
"files": [
{
"uri": "/PoAdef45_0652746727640.pdf"
}
]
}
],
"tos_policies_value": "e9414388-fbdf-4407-b5c2-bc39eae3645b"
}
'const url = 'https://sandbox.api.engagexpay.com/v2/customers/{customer_id}/individual/attach';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
identifying_documents: [
{type: 'SELFIE', files: [{uri: '/AbAcQ4hn_0652746727637.pdf'}]},
{
type: 'DRIVERS_LICENSE',
number: 'DL987654321',
country: 'USA',
state: 'US-CA',
issue_date: '2019-06-01',
expiry_date: '2029-06-01',
files: [
{side: 'FRONT', uri: '/AbAcQ4hn_0652746727638.pdf'},
{side: 'BACK', uri: '/XyZ123mn_0652746727639.pdf'}
]
}
],
address_documents: [
{
type: 'BANK_STATEMENT',
country: 'USA',
files: [{uri: '/PoAdef45_0652746727640.pdf'}]
}
],
tos_policies_value: 'e9414388-fbdf-4407-b5c2-bc39eae3645b'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://sandbox.api.engagexpay.com/v2/customers/{customer_id}/individual/attach")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"identifying_documents\": [\n {\n \"type\": \"SELFIE\",\n \"files\": [\n {\n \"uri\": \"/AbAcQ4hn_0652746727637.pdf\"\n }\n ]\n },\n {\n \"type\": \"DRIVERS_LICENSE\",\n \"number\": \"DL987654321\",\n \"country\": \"USA\",\n \"state\": \"US-CA\",\n \"issue_date\": \"2019-06-01\",\n \"expiry_date\": \"2029-06-01\",\n \"files\": [\n {\n \"side\": \"FRONT\",\n \"uri\": \"/AbAcQ4hn_0652746727638.pdf\"\n },\n {\n \"side\": \"BACK\",\n \"uri\": \"/XyZ123mn_0652746727639.pdf\"\n }\n ]\n }\n ],\n \"address_documents\": [\n {\n \"type\": \"BANK_STATEMENT\",\n \"country\": \"USA\",\n \"files\": [\n {\n \"uri\": \"/PoAdef45_0652746727640.pdf\"\n }\n ]\n }\n ],\n \"tos_policies_value\": \"e9414388-fbdf-4407-b5c2-bc39eae3645b\"\n}")
.asString();import requests
url = "https://sandbox.api.engagexpay.com/v2/customers/{customer_id}/individual/attach"
payload = {
"identifying_documents": [
{
"type": "SELFIE",
"files": [{ "uri": "/AbAcQ4hn_0652746727637.pdf" }]
},
{
"type": "DRIVERS_LICENSE",
"number": "DL987654321",
"country": "USA",
"state": "US-CA",
"issue_date": "2019-06-01",
"expiry_date": "2029-06-01",
"files": [
{
"side": "FRONT",
"uri": "/AbAcQ4hn_0652746727638.pdf"
},
{
"side": "BACK",
"uri": "/XyZ123mn_0652746727639.pdf"
}
]
}
],
"address_documents": [
{
"type": "BANK_STATEMENT",
"country": "USA",
"files": [{ "uri": "/PoAdef45_0652746727640.pdf" }]
}
],
"tos_policies_value": "e9414388-fbdf-4407-b5c2-bc39eae3645b"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.api.engagexpay.com/v2/customers/{customer_id}/individual/attach"
payload := strings.NewReader("{\n \"identifying_documents\": [\n {\n \"type\": \"SELFIE\",\n \"files\": [\n {\n \"uri\": \"/AbAcQ4hn_0652746727637.pdf\"\n }\n ]\n },\n {\n \"type\": \"DRIVERS_LICENSE\",\n \"number\": \"DL987654321\",\n \"country\": \"USA\",\n \"state\": \"US-CA\",\n \"issue_date\": \"2019-06-01\",\n \"expiry_date\": \"2029-06-01\",\n \"files\": [\n {\n \"side\": \"FRONT\",\n \"uri\": \"/AbAcQ4hn_0652746727638.pdf\"\n },\n {\n \"side\": \"BACK\",\n \"uri\": \"/XyZ123mn_0652746727639.pdf\"\n }\n ]\n }\n ],\n \"address_documents\": [\n {\n \"type\": \"BANK_STATEMENT\",\n \"country\": \"USA\",\n \"files\": [\n {\n \"uri\": \"/PoAdef45_0652746727640.pdf\"\n }\n ]\n }\n ],\n \"tos_policies_value\": \"e9414388-fbdf-4407-b5c2-bc39eae3645b\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"data": {
"customer_id": "55bd6b4e-c20a-4cc8-9535-91d5557a67d9"
},
"meta": null
}{
"status": 400,
"message": "Malformed request body"
}{
"message": "Authentication failed"
}{
"error": {
"code": "forbidden",
"message": "Customer is not eligible for this operation"
}
}{
"message": "Resource not found"
}{
"error": {
"code": "conflict",
"message": "An attach request is already in progress for this customer"
}
}{
"message": "<string>",
"errors": [
{}
]
}{
"status": 500,
"message": "Internal server error"
}- Upload files first using the Upload document endpoint to obtain the URIs needed for the
filesarrays, then reference them here. - The
tos_policies_valueshould be parsed from thetos_policies_urlquery parameter returned from the Create Individual Customer endpoint. - Maximum file size is 5 MB per file.
Prerequisites
The customer must satisfycustomer_type = INDIVIDUAL, api_version = v2, and a customer_status of INCOMPLETE or ACTION_REQUIRED. Any other state returns 403. Only one attach can be in flight per customer; a second concurrent attach returns 409.
Identity Document Side Requirements
| Type | Files | Sides |
|---|---|---|
PASSPORT | 1 | Side optional |
NATIONAL_ID | 2 | One FRONT and one BACK |
DRIVERS_LICENSE | 2 | One FRONT and one BACK |
RESIDENCE_PERMIT | 2 | One FRONT and one BACK |
SELFIE | 1 | Side optional |
Key Rules
- At most one non-SELFIE document may be included in
identifying_documents. To switch the primary document type, re-attach with the new type. stateis required whentypeisDRIVERS_LICENSEandcountryisUSA. It is optional for aDRIVERS_LICENSEissued elsewhere, and forbidden forPASSPORT,NATIONAL_ID, andRESIDENCE_PERMIT.- Exactly one
address_documentsentry is required. - File URIs must be unique across the entire request (SELFIE files excluded) and must belong to this customer.
- A
SELFIEentry may be required depending on your client configuration. When required, include exactly oneSELFIEentry carrying at least one file.
Authorizations
Bearer token authentication. Obtain token from Issue a Token endpoint
Path Parameters
Unique identifier for the individual customer
Body
application/json
Government-issued identity documents. Include at most one non-SELFIE primary document (PASSPORT, NATIONAL_ID, DRIVERS_LICENSE, or RESIDENCE_PERMIT) plus an optional SELFIE entry. NATIONAL_ID, DRIVERS_LICENSE, and RESIDENCE_PERMIT require both FRONT and BACK files.
Minimum array length:
1Show child attributes
Show child attributes
Proof of address. Exactly one entry is required.
Required array length:
1 elementShow child attributes
Show child attributes
Parsed from the tos_policies_value query parameter in the tos_policies_url returned by POST /v2/customers/individual. Signifies the customer has accepted the Terms of Service.
Example:
"e9414388-fbdf-4407-b5c2-bc39eae3645b"
⌘I