Sign up

Customers

Add and update customers from your own system, with their segments and activity.

A customer is someone your business knows, by phone, email or both. Your system adds them as they buy or sign up, segments them, and records their activity, so the right people get the right messages.

Requirements

  • An API key with the customers.write permission. Segments also need segments.write, and activities activity.write.

Requests

POST /v1/customers

Request syntax

{
  "ifExists": "<IF_EXISTS>",
  "ifSegmentMissing": "<IF_SEGMENT_MISSING>",
  "customers": [
    {
      "name": "<NAME>",
      "phone": "<PHONE_NUMBER>",
      "email": "<EMAIL>",
      "attributes": { "<KEY>": "<VALUE>" },
      "segments": [{ "name": "<SEGMENT>" }],
      "activities": [{ "key": "<ACTIVITY>", "value": "<ACTIVITY_VALUE>" }]
    }
  ]
}
PlaceholderDescriptionSample value
<IF_EXISTS>String. Optional. error, the default, or update: a customer someone already has is updated instead.update
<IF_SEGMENT_MISSING>String. Optional. error, the default, or create: a segment named by name is added.create
<NAME>String. Their name.Amina Juma
<PHONE_NUMBER>String. With the country code. Send a phone, an email, or both.+255712345678
<EMAIL>String. Their email address.amina@example.com
<KEY>, <VALUE>Object. Optional. Their details, used as {{attributes.x}}. Sent with update, they replace theirs.{ "plan": "gold" }
<SEGMENT>String. Optional. A segment by name, or by id. They're added to it, never taken out of others.Shoppers
<ACTIVITY>, <ACTIVITY_VALUE>Optional. Their activity. See Activity.purchased, Shoes

Example request

curl https://api.goomzo.africa/v1/customers \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ifExists": "update",
    "customers": [{
      "name": "Amina Juma",
      "phone": "+255712345678",
      "attributes": { "plan": "gold" },
      "segments": [{ "name": "Shoppers" }],
      "activities": [{ "key": "purchased", "value": "Shoes" }]
    }]
  }'

Responses

The answer is 201 when any customer was added, otherwise 200. It lists each customer with its result: created, updated or unchanged.

Notes

  • All or none: up to 100 customers at once. A problem with any of them saves nobody, and the error names it, such as customers[1].phone or customers[0].segments[2].
  • Finding someone: an existing customer is found by phone first, then by email.
  • A checkout: "ifExists": "update" suits a system that doesn't know whether the person is new.
  • Segment names: match whatever their case, so lead finds Lead rather than adding another.
  • Other requests: GET /v1/customers lists them, PATCH /v1/customers/{id} changes one, and POST /v1/customers/import takes a file.

Next steps

Last updated