Customer

INFO

This documentation is work in progress and subject to change. If you have any questions or feedback, please reach out to us via Support.

This object represents a customer of your business. It lets you manage your customer data that can apply for funding requests.

Delete operation is not supported

For regulation purposes, we do not support delete operation for customer object.

If you still need to delete a customer for a certain circumstances, please reach out to us via Support.

Customer Object

Property	Type	Description
customer_id	string	Unique identifier of the customer object (Assigned by Zetl).
external_customer_id	string	Partner-supplied ID, used by partner to uniquely identify the customer (This can be your own internal implementation of Customer ID).
contact_email	string	Customer contact person's email
contact_name	string	Customer contact person's name
contact_phone	string	E.164 international standard representation of contact person's phone number
contact_country	string (exactly 2)	Customer contact person's country
company_name	string	Customer company's name
company_country	string (exactly 2)	ISO 3166-1 alpha-2 codes (two-letter) representation of customer company's country of incorporation
company_sector	string	Customer company's business sector
created_at	string	Resource creation ISO datetime string (UTC)
updated_at	string	Resource last modified ISO datetime string (UTC)

Customer Object Example

JSON

{
  "customer_id": "b8a1dfe0-c575-4d5c-9840-2fca96b5d96a",
  "external_customer_id": "f849111b-c6c8-4774-be27-a4b4615429a3",
  "contact_email": "foo@example.com",
  "contact_name": "Foo Bar",
  "contact_phone": "+85224141219",
  "contact_country": "HK",
  "company_name": "Foo Bar",
  "company_country": "HK",
  "company_sector": "Recruitment",
  "created_at": "2023-12-01T00:00:00Z",
  "updated_at": "2023-12-01T00:00:00Z"
}

Create a Customer

POST   /v1/customers

https://api.zetl.com/v1/customers

Create a new customer to be used in funding requests. Creating a customer will also automatically create the KYC resource of its country of registration.

Request Properties

Property	Type	Description
customer_id	string	Partner-supplied ID, used by partner to uniquely identify the customer (This can be your own internal implementation of Customer ID).
contact_email	string	Customer contact person's email
contact_name	string	Customer contact person's name
contact_phone	string	E.164 international standard representation of contact person's phone number
contact_country	string (exactly 2)	Customer contact person's country
company_name	string	Customer company's name
company_country	string (exactly 2)	ISO 3166-1 alpha-2 codes (two-letter) representation of customer company's country of incorporation
company_sector	string	Customer company's business sector

Request Example

HTTP

POST /v1/customers HTTP/1.1
Host: api.zetl.com
Content-Type: application/json
Authorization: Bearer <your-private-key>
Idempotency-Key: 88a3db9c-0f14-4a58-b1f6-8b2c43f8e2a1

{
  "external_customer_id": "f849111b-c6c8-4774-be27-a4b4615429a3",
  "contact_email": "foo@example.com",
  "contact_name": "Foo Bar",
  "contact_phone": "+85224141219",
  "contact_country": "HK",
  "company_name": "Foo Bar",
  "company_country": "HK",
  "company_sector": "Recruitment"
}

curl

curl --request POST \
  --url 'https://app.zetl.com/v1/customers' \
  --header 'Authorization: Bearer <your-private-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 88a3db9c-0f14-4a58-b1f6-8b2c43f8e2a1' \
  --data '{
  "external_customer_id": "f849111b-c6c8-4774-be27-a4b4615429a3",
  "contact_email": "foo@example.com",
  "contact_name": "Foo Bar",
  "contact_phone": "+85224141219",
  "contact_country": "HK",
  "company_name": "Foo Bar",
  "company_country": "HK",
  "company_sector": "Recruitment"
}'

Response Properties

Refer to Customer object

Possible Errors

See Handling Error for generic possible errors.

Retrieve List of Customers

GET   /v1/customers

https://api.zetl.com/v1/customers

Get a list of customers owned by your business.

Query Parameters

See Pagination for URL query parameters.

Response Properties

Property	Type	Description
items	array of Customer	List of customer owned by your business.
count	number	Total number of customer owned by your business.

Response Example

JSON

{
  "items": [
    {
      "customer_id": "b8a1dfe0-c575-4d5c-9840-2fca96b5d96a",
      "external_customer_id": "f849111b-c6c8-4774-be27-a4b4615429a3",
      "contact_email": "foo@example.com",
      "contact_name": "Foo Bar",
      "contact_phone": "+85224141219",
      "contact_country": "HK",
      "company_name": "Foo Bar",
      "company_country": "HK",
      "company_sector": "Recruitment",
      "created_at": "2023-12-01T00:00:00Z",
      "updated_at": "2023-12-01T00:00:00Z"
    }
  ],
  "count": 1
}

Possible Error

See Handling Error for generic possible errors.

Retrieve a Customer resource

GET   /v1/customers/{customer_id}

https://api.zetl.com/v1/customers/{customer_id}

Get details of a customer owned by your business.

Response Properties

Refer to Customer object

Possible Error

See Handling Error for generic possible errors.

Update a Customer

PUT   /v1/customers/{customer_id}

https://api.zetl.com/v1/customers/{customer_id}

Update details of a customer owned by your business. This endpoint expect you to fully send the complete Customer properties with its updated values.

Request Properties

Customer country cannot be changed

Due to regulatory reason we disallow updates on company_country property.

Property	Type	Description
customer_id	string	Partner-supplied ID, used by partner to uniquely identify the customer (This can be your own internal implementation of Customer ID).
contact_email	string	Customer contact person's email
contact_name	string	Customer contact person's name
contact_phone	string	E.164 international standard representation of contact person's phone number
contact_country	string (exactly 2)	Customer contact person's country
company_name	string	Customer company's name
company_sector	string	Customer company's business sector

Request Example

HTTP

POST /v1/customers HTTP/1.1
Host: api.zetl.com
Content-Type: application/json
Authorization: Bearer <your-private-key>

{
  "external_customer_id": "f849111b-c6c8-4774-be27-a4b4615429a3",
  "contact_email": "foo@example.com",
  "contact_name": "Foo Bar",
  "contact_phone": "+85224141219",
  "contact_country": "HK",
  "company_name": "Foo Bar",
  "company_country": "HK",
  "company_sector": "Consulting"
}

curl

curl --request POST \
  --url "https://api.zetl.com/v1/customers" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <your-private-key>" \
  --data '{
  "external_customer_id": "f849111b-c6c8-4774-be27-a4b4615429a3",
  "contact_email": "foo@example.com",
  "contact_name": "Foo Bar",
  "contact_phone": "+85224141219",
  "contact_country": "HK",
  "company_name": "Foo Bar",
  "company_country": "HK",
  "company_sector": "Consulting"
}'

Response Properties

Refer to Customer object

Possible Error

See Handling Error for generic possible errors.