API Documentation
Users
POST /users
This is a single endpoint to invite users to the system and/or give them points.
Users are matched based on their email address and phone number, and are dynamically created if they do not already exist.
The only required field for each user is email - all others are optional.
The response will echo back your provided data, standardizing to our formatting if necessary, as well as filling in any missing data.
Of particular note, the response will always have an id field.
This can be useful for convenience, but is not necessary to record
as you can always look up a user later with the GET /users endpoint.
The response will also adjust the number of points to reflect the user's current total.
Currently, points is always 0 or a positive integer, but it may be allowed to go negative in the future.
One User at a Time
Request POST /api/v1/users:
{
email: 'user@Example.Com',
phone: '555-555-5555',
full_name: 'John Doe',
birthdate: '2000-01-31',
points: 100
}
Response (200):
{
user: {
id: 'ea3fca7c-0997-4055-ab63-e1ff4ce5bc0c',
email: 'user@example.com',
phone: '+15555555555',
full_name: 'John Doe',
birthdate: '2000-01-31',
points: 200
}
}
Batch Multiple Users at Once
If you have many users to update then it's preferable to batch them in a single request.
Batch data must be put in a users array,
which has a minimum length of 1 and a maximum length of 1000.
Batches are transactional - if even a single entity fails (e.g. because an invalid email address was provided) then the entire request fails and any changes are rolled back. This allows for easy retries without having to worry about partial failures.
Just as with a single user, the provided data will be echoed back with possible adjustments,
always including an id and the most current points value.
In this case, the response will be a users array returned in the same order it was provided.
Request POST /api/v1/users:
{
users: [{
email: 'user@example.com',
phone: '555-555-5555',
full_name: 'John Doe',
birthdate: '2000-01-31',
points: 0
}, {
email: 'user2@example.com',
points: 50
}]
}
Response (200):
{
users: [{
id: 'ea3fca7c-0997-4055-ab63-e1ff4ce5bc0c',
email: 'user@example.com',
phone: '+15555555555',
full_name: 'John Doe',
birthdate: '2000-01-31',
points: 0
}, {
id: '8c072cfb-efa6-45b6-be08-0012d4915e4e',
email: 'user2@example.com',
phone: null,
full_name: null,
birthdate: null,
points: 150
}]
}
GET /users
This endpoint returns an array of users associated with your organization. It uses the same fields and formatting as the other endpoints on this page.
Users are sorted most recently added first.
There is currently a limit where this will only return up to 1000 users.
Request GET /api/v1/users
Response (200):
{
users: [{
id: 'ea3fca7c-0997-4055-ab63-e1ff4ce5bc0c',
email: 'user@example.com',
phone: '+15555555555',
full_name: 'John Doe',
birthdate: '2000-01-31',
points: 0
}, {
id: '8c072cfb-efa6-45b6-be08-0012d4915e4e',
email: 'user2@example.com',
phone: null,
full_name: null,
birthdate: null,
points: 150
}]
}
Optional Parameters
Providing an email will attempt to lookup a user with that email address, and will return an array of either length 0 or 1, depending on whether a match is found or not.
As emails are considered unique identifiers in our system, this method is equally as fast as looking up a user by id.
Please ensure emails are properly URL encoded!
NOTE: There are many additional filtering and sorting options planned for this endpoint, as it is under active development. If you have any particular use case in mind please contact us and let us know what you'd like to see here.
Request GET /api/v1/users?email=test%2B1@example.com
Response (200):
{
users: [{
id: 'ff7bc64d-b34a-4c33-b5b9-06c5f4b9e10c',
email: 'text+1@example.com',
phone: '+15555555556',
full_name: 'Jane Doe',
birthdate: null,
points: 0
}]
}
GET /users/:id
This endpoint looks up a single user based on the id.
If the user is not found this will respond with a 404 status code.
Request GET /api/v1/users/ff7bc64d-b34a-4c33-b5b9-06c5f4b9e10c
Response (200):
{
user: {
id: 'ff7bc64d-b34a-4c33-b5b9-06c5f4b9e10c',
email: 'text+1@example.com',
phone: '+15555555556',
full_name: 'Jane Doe',
birthdate: null,
points: 0
}
}
GET /users/:id/rewards
This endpoint returns an array of a user's rewards, sorted by most recent first. These rewards represent a history of events for the user, where reward points were added and/or removed.
There is currently a limit of 300 rewards returned.
Note that rewards can have both points_added and points_removed at the same time,
and that those two fields are always 0 or a positive integer - it is not possible for them to have negative values.
If the user is not found this will respond with a 404 status code.
Request GET /api/v1/users/ff7bc64d-b34a-4c33-b5b9-06c5f4b9e10c/rewards
Response (200):
{
rewards: [{
created_at: '2023-07-01T17:22:01.500170',
points_added: 100,
points_removed: 0
}, {
created_at: '2023-03-21T09:13:31.900280',
points_added: 0,
points_removed: 50
}, {
created_at: '2022-11-25T15:21:03.321170',
points_added: 7,
points_removed: 8
}
}