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.

💡 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": {...}  

}

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.

Payload fields:

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

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:

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.

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