Cello API

Introductions

You can interact with the Cello API through HTTP requests from any language. Cello API provides 3 endpoints: Events to report and push (generic) events directly to Cello, Referral Codes to validate referral code (UCC) and Active link to retrieve an active referral code (UCC) and invite link for your user.

Domain base URL's

Use the Domain base URL that corresponds with the environment.

Endpoint URL	Environment
`https://api.sandbox.cello.so/`	Dev and Stage
`https://api.cello.so/`	Prod

💡 Switch environments in the Portal using a switch to get the credentials

Authentication

To use the Cello API, you need to authenticate the request using an accessToken which is passed in the Authorization request header.

To obtain them you will need accessKeyId & secretAccessKey which you can get from your product dashboard on Access Keys page.

The value of expiresIn specifies after how many seconds the token expires.

Obtain accessToken & refreshToken

curl -X POST https://api.cello.so/token \ -H "Content-Type: application/json" \ -d '{ "accessKeyId": "<accessKeyId>", "secretAccessKey": "<secretAccessKey>" }' { "accessToken": "<accessToken>", "expiresIn": 18000, // specifies after how many seconds the token expires "refreshToken": "<refreshToken>" } Status Code 201

Refresh accessToken

curl -X POST https://api.cello.so/token \ -H "Content-Type: application/json" \ -d '{ "refreshToken": "<refreshToken>" }' { "accessToken": "<accessToken>", "expiresIn": 18000 // specifies after how many seconds the token expires } Status Code 201

Events (Generic Events API) /events

This API provides a way to report and push referral update events to Cello.

Use cases:

New user signs up for your product based on a referral link.
New user schedules a demo call based on a referral link.
New user buys a subscription directly after the signup or after he or she tested the product.
New user cancels his or her subscription.
New user adds new seats to his or her active plan.

Basic Event Envelope

{ "eventName": "ReferralUpdated", "payload": {...}, "context": {...} }

Important

The eventName with Value ReferralUpdated is always required

Payload

The payload is the main body of the event and usually contains all the necessary data for Cello to be able to accept and process your event. It is being validated based on a prescribed structure.

Important

All additional fields present in the payload are stripped away. If you want to pass custom fields, consider using the context.

Payload fields:

The parameter ucc and newUserId must be always present in the payload.

Name	Type	Comment	Required
ucc	String	The used ucc of the referral	Yes
newUserId	String	A reference to the Id of the referred (new) user within your system.	Yes
price	Number	The amount of the subscription or transaction in Cents	Optional
currency	String	ISO currency string eg. EUR, USD, GBP or PLN	Optional

Context

Please add additional metadata in the context that helps Cello to attribute the event. It supports all valid JSON objects.

Pre-defined fields for the context:

Name	Type	Comment or Example
event.trigger	String	Action that triggered the referral event. Pre-defined options: “new-signup” “demo-call-booked” “demo-call-attended” “demo-call-canceled” “subscription-created” “subscription-updated” “subscription-canceled” “invoice-paid”
event.timestamp	timestamp	“2022-10-05 14:14:34”, “2022-11-20T03:18:01.620Z”, …
newUser.id	String	A reference to the Id of the new user within your system.
newUser.email	String	Email of the new user.
newUser.name	String	Name of the new user.
newUser.organizationId	String	Organization of the new user. Add this, if your referrers can refer an organization rather then a single user and you want to reward based on that.
subscription.id	String	A reference Id to subscription within your system.
subscription.interval	String	"one-time", "monthly", "quarterly", "yearly", "biennial", "triennial", "lifetime"
subscription.seatsUsed	String	Number of seats attached to a user account.
subscription.invoiceId	String	Unique Id of invoice (required for the invoice-paid event)

Pick your flow

Find out which flow suits your product and find the required events here.

Example Request

This is an example request for a new-signup event.

POST https://api.cello.so/events { "eventName": "ReferralUpdated", "payload": { "ucc": "cello-ucc", "newUserId": "new-user-product-user-id", "price": 0, "currency": "" }, "context": { "newUser": { "id": "new-user-product-user-id", "email": "new_user@gmail.com", "name": "New user name", "organizationId": "New user organization" }, "event": { "trigger": "new-signup", "timestamp": "2022-10-05 14:14:34" } } }

Example Response

Successful

{ "success": true } 200 OK

Invalid

{ "message": "<error message>" } 400 Bad Request

Referral codes /referral-codes

Referral codes endpoint allows you to find out which user does the referral code i.e. unique campaign code and check if the the unique campaign code is valid.

Checking who the code belongs to

If you need to find out which one of your users has referred a new user, you can simply pass the unique campaign code which the new user signed up with and we will return the user's productUserId this ucc belongs to.

Don't store ucc to productUserId mapping

We advice not to store the mapping between the ucc and the productUserId, as you can always retrieve it over the API and one user can have multiple ucc's as they as they identify a campaign.

Validating unique campaign codes

Most of referral programs award / provide discounts to new users if they were invited by someone using a referral program. A referred user will have a UCC of a user who referred them attached to them and that is mostly how you identify if they are eligible for this kind of discount.

To make sure that the discounts are applied correctly and the UCC has not been compromised along the way, you need to make sure that it is a valid UCC before applying a discount

Request

curl --location --request GET 'https://api.cello.so/referral-codes/UIPIWa2Hnnr' \ --header 'Authorization: Bearer accessToken'

Response

Valid UCC

{ "code": "UIPIWa2Hnnr", "productUserId":"12345678" "valid": true, "campaignId": "campaign_partners_1" } 200 OK

Invalid UCC - user does not exist

{ "code": "UIPIWa2Hnnr", "productUserId":"", "valid": false, "campaignId": "" } 200 OK

Invalid UCC - user blocked

{ "code": "UIPIWa2Hnnr", "productUserId":"12345678", "valid": false, "campaignId": "" } 200 OK

Active link /active-link

/active-link endpoint allows you retrieve an active ucc and invite link for your user. Using this endpoint, you can implement a range of use cases for Contextual sharing to increase the reach of your referral program.

Request

To get the current active link and ucc for your user, pass productUserId in the request

curl -X GET https://api.cello.so/referral-codes/active-link/:productUserId \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <accessToken>" \

Response

In the response you will receive users active ucc and their full invite link

{ "activeUcc": "UPobYBDuu0N", "link": "moonly.cello.so/UPobYBuu0N" } 200 OK

Returns

activeUcc - active unique campaign code or referral code for the current logged in user
link - personal invite link for the current logged in user

Last updated on

Was this page helpful?