API overview

The Goomzo API lets your own systems, such as your shop or point of sale, work with Goomzo. Add customers as they buy, record what they do, and send them messages, without anyone copying data by hand.

https://api.goomzo.africa/v1

Requests and responses are JSON. Every request is made by a service account, and can only do what its permissions allow.

Before you startCopy Anchor Link

1. Create a service account with the permissions you need.
2. Create an access token for it, and keep it somewhere safe, such as an environment variable.

While you build, use a test service account: it works against the real API, but its messages reach no one and use no SMS.

Make your first requestCopy Anchor Link

Add a customer:

curl https://api.goomzo.africa/v1/customers \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Amina Juma", "phone": "+255712345678"}'

Record what they did. It shows in their activity:

curl https://api.goomzo.africa/v1/customers/$CUSTOMER_ID/activity \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "purchased", "value": "Shoes"}'

An activity's key is lower case letters, numbers and _, up to 40 characters. Its value is text, a number or true/false. Add occurredAt to record something that happened earlier.

Send an SMS to a phone number:

curl https://api.goomzo.africa/v1/messages \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "0712345678", "channel": "sms", "body": "Thank you for shopping with us!"}'

to is a phone number for SMS, or an email address for email. If one of your customers has it, the message shows in their history. If not, it's still sent, under the number itself, and no customer is added. To send to a customer you know, use customerId instead of to.

Send the same SMS to several numbers with a broadcast:

curl https://api.goomzo.africa/v1/broadcasts \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Order ready", "to": ["0712345678", "0787654321"], "channel": "sms", "body": "Your order is ready."}'

A broadcast's to takes up to 10,000 numbers. Every one is checked first: if any isn't valid, nothing is sent, and the error names each bad one, such as to[1]. A number listed twice gets one copy.

What you can doCopy Anchor Link

ListsCopy Anchor Link

Lists come a page at a time, 50 by default. Ask for up to 200 with limit. To get the next page, send the nextCursor from the last one as cursor. Lists also return a total.

curl "https://api.goomzo.africa/v1/customers?limit=200&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $GOOMZO_TOKEN"

Next stepsCopy Anchor Link