Skip to main content

Create and Search Customers

Create a New Customer​

Send a POST request to the Create a New Customer endpoint to create a new customer. The request body for creating a new customer includes the following:

cURL
curl --location --request POST 'https://api.playbox.grow.curacel.co/api/v1/customers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data-raw '{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "ref": "189jwsp1",
  "middle_name": "Smith",
  "sex": "M",
  "birth_date": "1990-10-10",
  "bvn": "93201832987",
  "occupation": "Accountant",
  "city": "Ikeja",
  "residential_address": "6, city street, Lagos, Nigeria",
  "state": "Lagos",
  "nationality": "Nigerian",
  "country": "Nigeria",
  "next_of_kin_name": "Jane Doe",
  "next_of_kin_phone": "pariatur velit nulla anim",
  "proof_of_address": {
    "type": "Electricity bill",
    "url": "https://example.com/proof_of_address.jpg"
  }
}'

The following parameters may be omitted

  • bvn
  • proof_of_address
  • ref (will be automatically generated)

In a real-time production environment, if the above parameters are absent, the customer will get an email notification with instructions to provide them.

A successful request returns a 201 response with a new customer created, identified by their unique ref.

JSON
{
    "id": 7906,
    "ref": "189jwsf7",
    "first_name": "John",
    "last_name": "Doe",
    "birth_date": "1990-10-10T00:00:00.000000Z",
    "email": "john.doe@example.com",
    "phone": null
}
One Customer Cannot be Created Twice!

Ensure you type different details when trying to create a new customer, else a 422 error will be displayed!

Search for Existing Customers​

You can check if the information of your customer exists on the database, you may use the List Customers endpoint to search. The search query will be checked against:

  • customer's name
  • email
  • ref
  • phone

To ensure that only a piece of single customer information is returned in the search result and eliminate further processing at your end, we recommend the following guidelines:

  1. Search with customer ref: Though the customer's ref is not required when creating a new customer since it will automatically generate when omitted, we highly recommend that you set this yourself or store the auto-generated one from the response object against the customer's information in your database. You can then use it to search if the customer exists on our API.

  2. Search with email: If however, your application requires customers to have unique email addresses, you may search with a customer's email address to achieve the same result. Please note that we do not enforce unique email addresses when storing your customers' information.

cURL
curl --request GET \
     --url 'https://api.playbox.grow.curacel.co/api/v1/customers?search=<customer-ref>' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer YOUR_API_KEY'

Example: Customer exists

The data array below contains exactly one customer info, indicating that the customer is already stored at the Grow server.

If you are performing the search with the customer's email, you should extract the ref from the response.

JSON
{
  "data": [
    {
      "ref": "<customer-ref>",
      "first_name": "John",
      "last_name": "Doe",
      "email": "customer1@example.com",
      "phone": null,
      "created_at": "2022-05-04T15:13:57.000000Z",
      "full_name": "John Doe"
    }
  ],
  "links": {
    "first": "https://api.playbox.grow.curacel.co/api/v1/customers?page=1",
    "last": "https://api.playbox.grow.curacel.co/api/v1/customers?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.playbox.grow.curacel.co/api/v1/customers?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://api.playbox.grow.curacel.co/api/v1/customers",
    "per_page": "15",
    "to": 1,
    "total": 1
  }
}

Example: Customer does not exist

The data array is empty, showing that the customer does not exist.

JSON
{
  "data": [],
  "links": {
    "first": "https://api.playbox.grow.curacel.co/api/v1/customers?page=1",
    "last": "https://api.playbox.grow.curacel.co/api/v1/customers?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": null,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.playbox.grow.curacel.co/api/v1/customers?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://api.playbox.grow.curacel.co/api/v1/customers",
    "per_page": "15",
    "to": null,
    "total": 0
  }
}