Customer API Reference

Discover how to create, retrieve, update, and manage customer records effortlessly using our Customer model. Explore the API endpoints and data structures available to streamline your CRM processes, personalize customer interactions, and provide exceptional customer experiences.

The Customer model

Customers play a pivotal role in the business ecosystem, intricately linked to various financial transactions. Businesses leverage customer relationships to generate and dispatch invoices and estimates. Customers, in turn, hold the authority to approve or reject these financial documents and fulfill payments, fostering a dynamic and interactive financial exchange.

Properties

Name
id
Type
string
Description
Unique identifier for the customer.
Name
name
Type
string
Description
The name for the customer.
Name
business_id
Type
string
Description
The ID of the business.
Name
customer_business_id
Type
string
Description
The ID of the customer business.
Name
email
Type
string
Description
The email of the customer.
Name
phone
Type
string
Description
The phone number of the customer.
Name
contact_first_name
Type
string
Description
The contact first name of the customer.
Name
contact_last_name
Type
string
Description
The contact last name of the customer.
Name
website
Type
string
Description
The Website URL.
Name
created_at
Type
integer
Description
Timestamp when the customer was created.
Name
updated_at
Type
integer
Description
Timestamp when the customer was last updated.
Name
due_amount
Type
string
Description
The due amount of the customer.
Name
billing_address
Type
object
Description
The billing address of the customer.
Name
shipping_address
Type
object
Description
The shipping address of the customer.

GETapi/v2/customers

List all customers

This endpoint allows you to retrieve a paginated list of all your customers.

Headers

Name
business
Type
string
Description
The ID of the business.

Optional Parameters

Name
limit
Type
integer
Description
Limit the number of customers returned.
Name
page
Type
integer
Description
Page number (for pagination).
Name
name
Type
string
Description
Filter records by name.
Name
email
Type
string
Description
Filter records by email.
Name
phone
Type
string
Description
Filter records by phone.

Request

GET

api/v2/customers

curl -G "https://payments.your-domain.com/api/v2/customers" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "data": [
    {
      "id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
      "name": "john",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "customer_business_id": "98ed68ce-6f2d-4f17-a08a-e7d7d7aef67d",
      "email": "john@yxz.com",
      "phone": null,
      "contact_first_name": "John",
      "contact_last_name": "Doe",
      "website": "https://crater.financial",
      "created_at": 1701150335,
      "updated_at": 1701150336,
      "due_amount": "9500",
      "status": "ACTIVE"
    }, {...}
  ]
}

POSTapi/v2/customers

Create a customer

This endpoint allows you to add a new customer to your customer list.

Parameters

Name
name
Type
string
Description
The name for the customer.
Name
email
Type
string
Description
The email of the customer.

Optional Parameters

Name
contact_first_name
Type
string
Description
The contact first name of the customer.
Name
contact_last_name
Type
string
Description
The contact last name of the customer.
Name
phone
Type
string
Description
The phone number of the customer.
Name
website
Type
string
Description
The Website URL.
Name
billing_address.name
Type
string
Description
Name of the billing area.
Name
billing_address.state
Type
string
Description
State where the business is registered.
Name
billing_address.city
Type
string
Description
City where the business is registered.
Name
billing_address.address_street_1
Type
string
Description
Billing Address line 1.
Name
billing_address.address_street_2
Type
string
Description
Billing Address line 2.
Name
billing_address.zip
Type
string
Description
Business area zip code.
Name
billing_address.phone
Type
string
Description
Phone number for billing area.
Name
shipping_address.name
Type
string
Description
Name of the shipping area.
Name
shipping_address.state
Type
string
Description
State for business shipping purposes.
Name
shipping_address.city
Type
string
Description
City for business shipping purposes.
Name
shipping_address.address_street_1
Type
string
Description
Shipping Address line 1.
Name
shipping_address.address_street_2
Type
string
Description
Shipping Address line 2.
Name
shipping_address.zip
Type
string
Description
Zip code for shipping area.
Name
shipping_address.phone
Type
string
Description
Phone number for shipping area.

Request

POST

api/v2/customers

curl "https://payments.your-domain.com/api/v2/customers" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"name\": \"john\",
    \"email\": \"john@xyz.com\",
    \"contact_first_name\": \"John\",
    \"contact_last_name\": \"Doe\",
    \"phone\": \"2345557788\",
    \"website\": \"https://crater.financial\",
    \"billing_address\": {
      \"name\": \"billing address\",
      \"address_street_1\": \"Address 1\",
      \"address_street_2\": \"Address 2\",
      \"city\": \"Los Angeles\",
      \"state\": \"CA\",
      \"zip\": \"91504\",
      \"phone\": \"2345557788\"
    },
    \"shipping_address\": {
      \"name\": \"shipping address\",
      \"address_street_1\": \"Address 1\",
      \"address_street_2\": \"Address 2\",
      \"city\": \"Los Angeles\",
      \"state\": \"CA\",
      \"zip\": \"91504\",
      \"phone\": \"2345557788\"
    }
  }"

Response

{
  "data": {
    "id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "name": "john",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "customer_business_id": "98ed68ce-6f2d-4f17-a08a-e7d7d7aef67d",
    "email": "john@xyz.com",
    "phone": "2345557788",
    "contact_first_name": "John",
    "contact_last_name": "Doe",
    "website": "https://crater.financial",
    "created_at": 1701257963,
    "updated_at": 1701257963,
    "due_amount": null,
    "billing_address": {
      "name": "billing address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "shipping_address": {
      "name": "shipping address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "status": "ACTIVE"
  }
}

GETapi/v2/customers/{id}

Retrieve a customer

This endpoint allows you to retrieve a customer by providing their id.

Parameters

Name
id
Type
integer
Description
The ID of the customer.

Request

GET

api/v2/customers/{id}

curl --request GET \
  --get "https://payments.your-domain.com/api/v2/customers/98ed68ce-6964-4c2a-9430-8a849e373c52" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "data": {
    "id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "name": "john",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "customer_business_id": "98ed68ce-6f2d-4f17-a08a-e7d7d7aef67d",
    "email": "john@xyz.com",
    "phone": "2345557788",
    "contact_first_name": "John",
    "contact_last_name": "Doe",
    "website": "https://crater.financial",
    "created_at": 1701257963,
    "updated_at": 1701257963,
    "due_amount": null,
    "billing_address": {
      "name": "billing address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "shipping_address": {
      "name": "shipinng address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "status": "ACTIVE"
  }
}

PUTapi/v2/customers/{id}

Update a customer

This endpoint allows you to perform an update on a customer.

Parameters

Name
id
Type
string
Description
The id of the customer.
Name
name
Type
string
Description
The name for the customer.
Name
email
Type
string
Description
The email of the customer.

Optional Parameters

Name
contact_first_name
Type
string
Description
The contact first name of the customer.
Name
contact_last_name
Type
string
Description
The contact last name of the customer.
Name
phone
Type
string
Description
The phone number of the customer.
Name
website
Type
string
Description
The Website URL.
Name
billing_address.name
Type
string
Description
Name of the billing area.
Name
billing_address.state
Type
string
Description
State where the business is registered.
Name
billing_address.city
Type
string
Description
City where the business is registered.
Name
billing_address.address_street_1
Type
string
Description
Billing Address line 1.
Name
billing_address.address_street_2
Type
string
Description
Billing Address line 2.
Name
billing_address.zip
Type
string
Description
Business area zip code.
Name
billing_address.phone
Type
string
Description
Phone number for billing area.
Name
shipping_address.name
Type
string
Description
Name of the shipping area.
Name
shipping_address.state
Type
string
Description
State for business shipping purposes.
Name
shipping_address.city
Type
string
Description
City for business shipping purposes.
Name
shipping_address.address_street_1
Type
string
Description
Shipping Address line 1.
Name
shipping_address.address_street_2
Type
string
Description
Shipping Address line 2.
Name
shipping_address.zip
Type
string
Description
Zip code for shipping area.
Name
shipping_address.phone
Type
string
Description
Phone number for shipping area.

Request

PUT

api/v2/customers/{id}

curl --request PUT \
  "https://payments.your-domain.com/api/v2/customers/98ed68ce-6964-4c2a-9430-8a849e373c52" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"name\": \"john\",
    \"email\": \"john@example.com\",
    \"phone\": \"2345557788\",
    \"contact_first_name\": \"John\",
    \"contact_last_name\": \"Doe\",
    \"website\": \"https://crater.financial\",
    \"billing_address\": {
      \"name\": \"billing address\",
      \"address_street_1\": \"Address 1\",
      \"address_street_2\": \"Address 2\",
      \"city\": \"Los Angeles\",
      \"state\": \"CA\",
      \"zip\": \"91504\",
      \"phone\": \"2345557788\"
    },
    \"shipping_address\": {
      \"name\": \"shipping address\",
      \"address_street_1\": \"Address 1\",
      \"address_street_2\": \"Address 2\",
      \"city\": \"Los Angeles\",
      \"state\": \"CA\",
      \"zip\": \"91504\",
      \"phone\": \"2345557788\"
    }
  }"

Response

{
  "data": {
    "id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "name": "John",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "customer_business_id": "98ed68ce-6f2d-4f17-a08a-e7d7d7aef67d",
    "email": "john@example.com",
    "phone": "2345557788",
    "contact_first_name": "John",
    "contact_last_name": "Doe",
    "website": "https://crater.financial",
    "created_at": 1681454330,
    "updated_at": 1681815749,
    "due_amount": "10000",
    "billing_address": {
      "name": "billing address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "shipping_address": {
      "name": "shipping address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "status": "ACTIVE"
  }
}

DELETEapi/v2/customers/{id}

Delete a customer

This endpoint allows you to delete a customer.

Parameters

Name
id
Type
integer
Description
The ID of the customer.

Request

DELETE

api/v2/customers/{id}

curl --request DELETE \
  "https://payments.your-domain.com/api/v2/customers/98ed68ce-6964-4c2a-9430-8a849e373c52" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
  "object": "Customer",
  "deleted": true
}