Create a Customer

Before you can set up a ledger for one of your customers, we need to know some information about them to comply with FCA regulations and to watch out for any money laundering activites etc.

POST /accounts/create_customer

Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Parameters

Parameter	Format	Length	Description
customer_type Required	`string`	7-10	The type of customer you are creating. Acceptable Values: "individual" "company"
first_name Required	`string`	1-20	The first name of the customer, it should match the value shown on their driving license or passport. Acceptable Characters: a-z A-Z - '
middle_name	`string`	0-20	The middle name of the customer, it should match the value shown on their driving license or passport. Acceptable Characters: a-z A-Z - '
last_name Required	`string`	0-20	The last name of the customer, it should match the value shown on their driving license or passport. Acceptable Characters: a-z A-Z - '
address Required	`object`
number Recommended	`string`	1-11	Account holder’s street number. Acceptable Characters: a-z A-Z 0-9
refinement	`string`	1-100	The address refinement, may include flat number, house name etc. e.g. Suite 2, 4th Floor. Acceptable Characters: a-z A-Z 0-9 . - _
street Recommended	`string`	1-100	Account holder's street address. Acceptable Characters: a-z A-Z 0-9 , . - _
region	`string`	1-100	The state, province, prefecture, or region. Acceptable Characters: a-z A-Z 0-9 , . - _
city Recommended	`string`	1-100	Account holder's city. Acceptable Characters: a-z A-Z 0-9 , . - _
postal_code Recommended	`string`	1-100	Account holder's ZIP or postal code. Acceptable Characters: a-z A-Z 0-9 , . - _
iso_country Required	`string`	2	Account holder's country, an ISO 3166 2-character code. Acceptable Characters: a-z A-Z
dob Required	`string`	10	Customer’s date of birth. Acceptable Characters: 0-9 in the format YYYY-MM-DD
email Recommended	`string`	1-50	Account holder's billing email address. Acceptable Characters: 0-9 a-z A-z _ - . @
phone Recommended	`string`	7-20	Account holder's phone number. Acceptable Characters: 0-9 ( ) + -

JSON

{
    "customer_type": "individual",
    "first_name": "Joe",
    "last_name": "Bloggs",
    "address": {
        "number": "44",
        "refinement": "Suite 2, 4th Floor",
        "street": "Baker Street",
        "city": "London",
        "postal_code": "W1U7AL",
        "iso_country": "GB"
    },
    "dob": "1988-10-03",
    "email": "support@acquired.com",
    "phone": "+44(0)203 982 6580"
}

Response

Parameter	Format	Length	Description
status	`int`	1-2	The outcome of the request.
message	`string`	0-100	Handy text describing the status for debugging.
data	`object`
customer_id	`string`	36	A unique reference for your newly created customer profile, will be used in future requests relating to this individual.

JSON

{
  "status": 1,
  "message": "Success",
  "data": {
    "customer_id": "859f4eef-6a53-4110-8757-371844df8e8c"
  }
}

Take note of the customer_id generated in the response, this will be used in subsequent API calls pertaining to the customer.

Authenticate a customer

Use this request to verify the identity of a customer and the details they have provided.

POST /accounts/customers/authenticate

Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Request

Parameter	Format	Length	Description
customer_id Required	`string`	36	The unique `customer_id` profile reference returned to you as part of the create customer reponse, please see here for more info. Acceptable Characters: a-z A-Z , . – _
third_party Required	`string`	0-50	The name of the organisation conducting your KYC process. Acceptable Values: "gb_group"
id_type Required	`string`	0-50	The type of the uploaded document. Acceptable Values: "passport" "driving_license" "id_card"
front Required	`object`
image Required	`string`	Max File Size: 4MB	Image data of the front side of the uploaded document in Base64 format. Acceptable Characters: A-Z a-z 0-9 + / =
mime_type Required	`string`	NA	The mime_type of the uploaded document. Acceptable Values: "image/jpeg" "image/bmp" "image/png" "application/pdf" "image/tiff"
back Conditional	`object`		Only required when `id_type` is either "driving_license" or "id_card".
image Conditional	`string`	Max File Size: 4MB	Image data of the back side of the uploaded document in Base64 format. Acceptable Characters: A-Z a-z 0-9 + / =
mime_type Conditional	`string`	NA	The mime_type of the uploaded document. Acceptable Values: "image/jpeg" "image/bmp" "image/png" "application/pdf" "image/tiff"
additional_data	`object`
image	`string`	Max File Size: 4MB	Image data of the front side of the uploaded document in Base64 format. Acceptable Characters: A-Z a-z 0-9 + / =
mime_type	`string`	NA	The mime_type of the uploaded document. Acceptable Values: "image/jpeg" "image/bmp" "image/png" "application/pdf" "image/tiff"

JSON

{
    "customer_id":"859f4eef-6a53-4110-8757-371844df8e8c",
    "third_party":"gb_group",
    "id_type":"driving_licesce",
    "front":{
        "image":"64BITFORMAT",
        "mime_type":"image/jpeg"
    },
    "back":{
        "image":"64BITFORMAT",
        "mime_type":"image/jpeg"
    },
    "additional_data":{
        "image":"65BITFORMAT",
        "mime_type":"application/pdf"
    }
}

Response

Parameter	Format	Length	Description
status	`int`	1-2	The outcome of the request.
message	`string`	0-100	Handy text describing the status for debugging.

JSON

{
    "status": 1,
    "message": "Success"
}

Customer Details

You can submit this query at anytime to retrieve the details we have on record against a specific customer_id.

GET /accounts/customers/{{customer_id}}

Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Response

Parameter	Format	Length	Description
status	`int`	1-2	The outcome of the request.
message	`string`	0-100	Handy text describing the status for debugging.
data	`object`
customer_id	`string`	36	If everything went as planned, we'll return the `customer_id` value.
active	`boolean`	4-5	A true / false value to let you know if the account is active or not.
customer_type	`string`	7-10	The customer could be set as either "individual" or "company".
name	`string`	1-50	The name of the customer, it should match the value shown on their driving license or passport.
address	`object`
number	`int`	1-100	The address number e.g. 2a.
refinement	`string`	1-100	The address refinement, may include flat number, house name etc e.g. Suite 2, 4th Floor.
street	`string`	1-100	Customer's street address.
region	`string`	1-100	The state, province, county, prefecture, or region.
city	`string`	1-100	Customer's city.
postal_code	`string`	1-100	Customer's ZIP or postal code.
iso_country	`string`	2	Customer's country, an ISO 3166 2-character code.
dob	`string`	10	Customer’s date of birth.
email	`string`	1-50	Customer's email address.
phone	`string`	7-20	Customer's phone number.
created	`string`	24	The date and time at which the account was created.
last_update	`string`	24	The date and time at which the last activity against the customers account took place.

JSON

{
    "status": 1,
    "message": "Success",
    "data": {
        "customer_id": "5e865d53-669c-4bbe-be49-09494cffc19d",
        "active": true,
        "customer_type": "individual",
        "name": "Joe Bloggs",
        "address": {
            "number": "5",
            "refinement": "Flat 2B",
            "street": "St John’s Place",
            "region": "London",
            "city": "London",
            "postal_code": "W1U 7AL",
            "iso_country": "GB"
        },
        "dob": "1988-03-10",
        "email": "testing@test.com",
        "phone": "+44(0)7763270200",
        "created": "2020-04-02 21:46:59",
        "last_update": "2020-04-23 10:32:17"
    }
}

Update Customer

Some information about your customer might change from time to time, use this request to let us know, we'll then update the customer_id to have the latest and most up to date information.

PUT /accounts/customers/{{customer_id}}

Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Parameters

Parameter	Format	Length	Description
address	`object`
number	`string`	1-11	Account holder's street number. Acceptable Characters: a-z A-Z 0-9
refinement	`string`	1-100	The address refinement, may include flat number, house name etc e.g. Suite 2, 4th Floor. Acceptable Characters: a-z A-Z 0-9 . - _
street	`string`	1-100	Account holder's street address. Acceptable Characters: a-z A-Z 0-9 , . - _
region	`string`	1-100	The state, province, county, prefecture, or region Acceptable Characters: a-z A-Z 0-9 , . - _
city	`string`	1-100	Account holder's city. Acceptable Characters: a-z A-Z 0-9 , . - _
postal_code	`string`	1-100	Account holder's ZIP or postal code. Acceptable Characters: a-z A-Z 0-9 , . - _
iso_country	`string`	2	Account holder's country, an ISO 3166 2-character code. Acceptable Characters: a-z A-Z
dob	`string`	10	Customer’s date of birth. Acceptable Characters: 0-9 in the format YYYY-MM-DD
email	`string`	1-50	Account holder's billing email address. Acceptable Characters: 0-9 a-z A-z _ - . @
phone	`string`	7-20	Account holder's phone number. Acceptable Characters: 0-9 ( ) + -

JSON

{
    "address": {
        "number": "123",
        "refinement": "Flat B",
        "street": "Fulham Road",
        "region": "Middlesex",
        "city": "London",
        "postal_code": "W69ER",
        "iso_country": "GB"
    },
    "dob": "1988-10-03",
    "email": "hello@acquired.com",
    "phone": "44 0 203 982 6580"
}

Response

Parameter	Format	Length	Description
status	`int`	1-2	The outcome of the request.
message	`string`	0-100	Handy text describing the status for debugging.
data	`object`
customer_id	`string`	36	If everything went as planned, we'll return the `customer_id` value.

JSON

{
    "status": 1,
    "message": "Success",
    "data": {
        "customer_id": "5ea06f6c-4405-4d54-a612-9120904df168"
    }
}

Enable/Disable Customer

PUT /accounts/customers/{{customer_id}}

Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Parameters

Parameter	Format	Length	Description
active Required	`boolean`	3	The status that you want to update the ledger to. Acceptable Values: "true" "false"

JSON

{
    "active": false
}

Response

Parameter	Format	Length	Description
status	`int`	1-2	The outcome of the request.
message	`string`	0-100	Handy text describing the status for debugging.
data	`object`
customer_id	`string`	36	This is the `customer_id` you have just updated.

JSON

{
    "status": 1,
    "message": "Success",
    "data": {
        "customer_id": "859f4eef-6a53-4110-8757-371844df8e8c"
    }
}

Get a list of customers

You can submit this request at any time to return a list of customers.

GET /accounts/customers/list

Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Response

Parameter	Format	Length	Description
status	`int`	1-2	The outcome of the request.
message	`string`	0-100	Handy text describing the status for debugging.
data	`object`
total	`int`	1-11	Number of objects in list.
list	`array`
customer_id	`string`	36	The unique customer profile reference returned to you as part of the create.
first_name	`string`	0-50	Customers first name.
middle_name	`string`	0-50	Customers middle name.
last_name	`string`	0-50	Customers last name.
customer_type	`string`	7-10	The customer type - could be either "individual" or "company".
ledger_count	`int`	4-5	The number of ledgers associated with the customer.
primary_use	`array`		An array of tags that describe what the account will be used for.
verified	`boolean`	4-5	A true / false value to let you know if the customers identity has been verified or not.
active	`boolean`	4-5	A true / false value to let you know if the account is active or not.

JSON

{
    "status": "1",
    "message": "Success",
    "data": {
        "total": "1",
        "list": [{
            "customer_id": "5b068bd4-ba1c-4b56-a23c-78e0ad2509c9",
            "first_name": "Joe",
            "middle_name": "",
            "last_name": "Bloggs",
            "customer_type": "individual",
            "ledger_count": "2",
            "primary_use": [
                "gbp",
                "eur",
                "usd"
            ],
            "verified": true,
            "active": true
        }]
    }
}