Skip to content

Propello Cloud API (3.0.0)

Overview:

The Propello API has been created to allow organisations to interact with the Propello platform. There are a lot of different options available to integrators but we will aim to introduce these over the next few sections to help you get up and running quickly.

The rate limit is set to 120 calls per minute, however this can be changed upon request. Please speak to your Customer Success Manager to arrange this. You can view your current rate limit in the CMS in the group settings under the “Integration” tab.

If you have any questions around the integration or onboarding, please email tech@propellocloud.com

SDKs
PHP
JavaScript
Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Mock server
https://propello-cloud.redocly.app/_mock/openapi

OAuth

OAuth Operations

Operations

User

User Operations

Operations

Create a new user record

Request

Security
BearerAuth
Bodyapplication/json

When deciding on your implementation consider if there is potential for a user’s email to change. By default we do not allow users added via API to change their email address, making your system the single point of truth for these changes. Also consider how our platform will be updated with email changes.

company_name should only be used if you would like to refer to your user as their company name, generally because your database does not hold a first_name & last_name.

Metadata

Additional metadata can be configured within the platform by a member of the Propello team, and updated by API. Metadata can be used to segment users in the platform for a number of reasons including reporting and targeted campaigns.

Welcome email & SMS

The group settings allow you to configure sending a new user added via the API an instant activation email and/or SMS with a tokenised URL to set their password. Once set, if you want to override this include either of the following variables in your request.

Email

"send_activation_email": true|false

SMS

"send_activation_sms": true|false

If the send_activation_sms flag is set to true you need to provide a "phone" attribute in your request.

organisation_group_idinteger
Example: 1
emailstringrequired
Example: "john.smith@example.org"
first_namestring
Example: "John"
last_namestring
Example: "Smith"
company_namestring
Example: "Parisian Inc"
UIDstring
Example: "ABC123"
metaobject
curl -i -X POST \
  https://propello-cloud.redocly.app/_mock/openapi/v3/user/create \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organisation_group_id": 1,
    "email": "john.smith@example.org",
    "first_name": "John",
    "last_name": "Smith",
    "company_name": "Parisian Inc",
    "UID": "ABC123",
    "meta": {
      "sales": 5,
      "location": "London"
    }
  }'

Responses

OK

Bodyapplication/json
statusinteger
Example: 200
timestampstring
Example: "1970-01-30T00:00:00.000000Z"
dataobject
Response
application/json
{
  "status": 200,
  "timestamp": "1970-01-30T00:00:00.000000Z",
  "data": {
    "id": 987654,
    "UID": "ABC123",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.org",
    "status": "Active",
    "created_at": "1970-01-30T00:00:00.000000Z"
  }
}

Bulk create new user records (limit 100)

Request

Security
BearerAuth
Bodyapplication/json

When deciding on your implementation consider if there is potential for a user’s email to change. By default we do not allow users added via API to change their email address, making your system the single point of truth for these changes. Also consider how our platform will be updated with email changes.

company_name should only be used if you would like to refer to your user as their company name, generally because your database does not hold a first_name & last_name.

Metadata

Additional metadata can be configured within the platform by a member of the Propello team, and updated by API. Metadata can be used to segment users in the platform for a number of reasons including reporting and targeted campaigns.

Welcome email

The group settings allow you to configure sending a new user added via the API an instant activation email and/or SMS with a tokenised URL to set their password. Once set, if you want to override this include either of the following variables in your request.

Email

"send_activation_email": true|false

send_activation_emailboolean
Example: false
dataArray of objects(CreateUserBody)
curl -i -X POST \
  https://propello-cloud.redocly.app/_mock/openapi/v3/user/create/bulk \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "send_activation_email": false,
    "data": [
      {
        "organisation_group_id": 1,
        "email": "john.smith@example.org",
        "first_name": "John",
        "last_name": "Smith",
        "company_name": "Parisian Inc",
        "UID": "ABC123",
        "meta": {
          "sales": 5,
          "location": "London"
        }
      }
    ]
  }'

Responses

ACCEPTED

Bodyapplication/json
statusinteger
Example: 202
timestampstring
Example: "1970-01-30T00:00:00.000000Z"
dataany
Example: []
Response
application/json
{
  "status": 202,
  "timestamp": "1970-01-30T00:00:00.000000Z",
  "data": []
}

Retrieve a users details

Request

Security
BearerAuth
Path
identifierstringrequired
Enum"id""email""UID"
Example: email
identifier_valuestringrequired
Example: john.smith@example.org
Bodyapplication/json

If accessing via an organisation level token you will need to provide an organisation group id in order to indicate which group the user belongs to.

organisation_group_idinteger
Example: 1
curl -i -X POST \
  https://propello-cloud.redocly.app/_mock/openapi/v3/user/get/email/john.smith@example.org \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organisation_group_id": 1
  }'

Responses

OK

Bodyapplication/json
statusinteger
Example: 200
timestampstring
Example: "1970-01-30T00:00:00.000000Z"
dataobject
Response
application/json
{
  "status": 200,
  "timestamp": "1970-01-30T00:00:00.000000Z",
  "data": {
    "id": 987654,
    "UID": "ABC123",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.org",
    "status": "Active",
    "created_at": "1970-01-30T00:00:00.000000Z"
  }
}

Retrieve a list of users

Request

Security
BearerAuth
curl -i -X POST \
  https://propello-cloud.redocly.app/_mock/openapi/v3/user/list \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/json
statusinteger
Example: 200
timestampstring
Example: "1970-01-30T00:00:00.000000Z"
dataArray of objects
Response
application/json
{
  "status": 200,
  "timestamp": "1970-01-30T00:00:00.000000Z",
  "data": [
    { … }
  ]
}

Update a user record

Request

Security
BearerAuth
Path
identifierstringrequired
Enum"id""email""UID"
Example: email
identifier_valuestringrequired
Example: john.smith@example.org
Bodyapplication/json

If accessing via an organisation level token you will need to provide an organisation_group_id in order to indicate which group the user belongs to.

organisation_group_idinteger
Example: 1
emailstringrequired
Example: "john.smith@example.org"
first_namestring
Example: "John"
last_namestring
Example: "Smith"
company_namestring
Example: "Parisian Inc"
UIDstring
Example: "ABC123"
metaobject
curl -i -X POST \
  https://propello-cloud.redocly.app/_mock/openapi/v3/user/update/email/john.smith@example.org \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organisation_group_id": 1,
    "email": "john.smith@example.org",
    "first_name": "John",
    "last_name": "Smith",
    "company_name": "Parisian Inc",
    "UID": "ABC123",
    "meta": {
      "sales": 5,
      "location": "London"
    }
  }'

Responses

OK

Bodyapplication/json
statusinteger
Example: 200
timestampstring
Example: "1970-01-30T00:00:00.000000Z"
dataobject
Response
application/json
{
  "status": 200,
  "timestamp": "1970-01-30T00:00:00.000000Z",
  "data": {
    "id": 987654,
    "UID": "ABC123",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.org",
    "status": "Active",
    "created_at": "1970-01-30T00:00:00.000000Z"
  }
}

Deactivate a user record

Request

Security
BearerAuth
Path
identifierstringrequired
Enum"id""email""UID"
Example: email
identifier_valuestringrequired
Example: john.smith@example.org
Bodyapplication/json

Deleting a user, revokes their access to the platform but retains all information stored against them.

We suggest implementing a process to reactivate users if there is potential that they may return. If a request to create a user that already exists in either an active or deleted state is posted to our system, we will reject it.

If accessing via an organisation level token you will need to provide an organisation group id in order to indicate which group the user belongs to.

organisation_group_idinteger
Example: 1
curl -i -X DELETE \
  https://propello-cloud.redocly.app/_mock/openapi/v3/user/delete/email/john.smith@example.org \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organisation_group_id": 1
  }'

Responses

OK

Bodyapplication/json
statusinteger
Example: 200
timestampstring
Example: "1970-01-30T00:00:00.000000Z"
dataany
Example: []
Response
application/json
{
  "status": 200,
  "timestamp": "1970-01-30T00:00:00.000000Z",
  "data": []
}

Restore a deactivated user record

Request

Security
BearerAuth
Path
identifierstringrequired
Enum"id""email""UID"
Example: email
identifier_valuestringrequired
Example: john.smith@example.org
Bodyapplication/json

If accessing via an organisation level token you will need to provide an organisation group id in order to indicate which group the user belongs to.

organisation_group_idinteger
Example: 1
curl -i -X POST \
  https://propello-cloud.redocly.app/_mock/openapi/v3/user/restore/email/john.smith@example.org \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organisation_group_id": 1
  }'

Responses

OK

Bodyapplication/json
statusinteger
Example: 200
timestampstring
Example: "1970-01-30T00:00:00.000000Z"
dataany
Example: []
Response
application/json
{
  "status": 200,
  "timestamp": "1970-01-30T00:00:00.000000Z",
  "data": []
}

Generate a single-use user login link

Request

Security
BearerAuth
Path
identifierstringrequired
Enum"id""email""UID"
Example: email
identifier_valuestringrequired
Example: john.smith@example.org
Bodyapplication/json

It may be necessary to redirect a user to our platform and automatically authenticate them. Using this endpoint your system can receive a URL which will authenticate the user.

If accessing via an organisation level token you will need to provide an organisation group id in order to indicate which group the user belongs to.

organisation_group_idinteger
Example: 1
curl -i -X POST \
  https://propello-cloud.redocly.app/_mock/openapi/v3/user/login-url/email/john.smith@example.org \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organisation_group_id": 1
  }'

Responses

OK

Bodyapplication/json
statusinteger
Example: 200
timestampstring
Example: "1970-01-30T00:00:00.000000Z"
dataobject
Response
application/json
{
  "status": 200,
  "timestamp": "1970-01-30T00:00:00.000000Z",
  "data": {
    "login_url": "https://example.yourperx.com/auth-token/BkfEhiym5mvKYSrAp5iQ0YnRTB9mdo3r9kLXe6EuEhTPoAONLNIJ8TNzGerJVwgX"
  }
}

Create a user and return a single-use login URL

Request

Security
BearerAuth
Bodyapplication/json

If you need to create a user and automatically generate a login URL.

If accessing via an organisation level token you will need to provide an organisation_group_id in order to indicate which group the user belongs to.

organisation_group_idinteger
Example: 1
emailstringrequired
Example: "john.smith@example.org"
first_namestring
Example: "John"
last_namestring
Example: "Smith"
company_namestring
Example: "Parisian Inc"
UIDstring
Example: "ABC123"
metaobject
return_user_detailsboolean

Return the created users details. Only applicable for login url.

Default false
curl -i -X POST \
  https://propello-cloud.redocly.app/_mock/openapi/v3/user/create/login-url \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organisation_group_id": 1,
    "email": "john.smith@example.org",
    "first_name": "John",
    "last_name": "Smith",
    "company_name": "Parisian Inc",
    "UID": "ABC123",
    "meta": {
      "sales": 5,
      "location": "London"
    },
    "return_user_details": false
  }'

Responses

OK

Bodyapplication/json
statusinteger
Example: 200
timestampstring
Example: "1970-01-30T00:00:00.000000Z"
dataobject
Response
application/json
{
  "status": 200,
  "timestamp": "1970-01-30T00:00:00.000000Z",
  "data": {
    "login_url": "https://example.yourperx.com/auth-token/BkfEhiym5mvKYSrAp5iQ0YnRTB9mdo3r9kLXe6EuEhTPoAONLNIJ8TNzGerJVwgX",
    "user": { … }
  }
}

Delete user and remove identifiable information

Request

Security
BearerAuth
Path
identifierstringrequired
Enum"id""email""UID"
Example: email
identifier_valuestringrequired
Example: john.smith@example.org
Bodyapplication/json

By default the users UID will be maintained, if you wish to remove this you will need to pass a maintain_uid of false. Please note, if you anonymise the UID you will need to retain the record ID returned if the user is to be restored at a later date.

If accessing via an organisation level token you will need to provide an organisation_group_id in order to indicate which group the user belongs to.

maintain_uidboolean
Default true
Example: true
curl -i -X POST \
  https://propello-cloud.redocly.app/_mock/openapi/v3/user/anonymise/email/john.smith@example.org \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "maintain_uid": true
  }'

Responses

OK

Bodyapplication/json
statusinteger
Example: 200
timestampstring
Example: "1970-01-30T00:00:00.000000Z"
dataobject
Response
application/json
{
  "status": 200,
  "timestamp": "1970-01-30T00:00:00.000000Z",
  "data": {
    "id": 987654,
    "UID": "ABC123",
    "first_name": null,
    "last_name": null,
    "email": null,
    "created_at": "1970-01-30T00:00:00.000000Z"
  }
}

Restore previously anonymised user

Request

Security
BearerAuth
Path
identifierstringrequired
Enum"id""UID"
Example: UID
identifier_valuestringrequired
Example: ABC1234
Bodyapplication/json

If you wish to obtain a login url for the user when restoring, you can send a get_login value of true and a login_url value will be appended to the response.

If accessing via an organisation level token you will need to provide an organisation_group_id in order to indicate which group the user belongs to.

emailstringrequired
Example: "john.smith@example.org"
UIDstring
Example: "ABC123"
first_namestring
Example: "John"
last_namestring
Example: "Smith"
company_namestring
Example: "Smith Co Ltd."
billing_phonestring
Example: "+441234567890"
billing_emailstring
Example: "accounts@example.org"
billing_address_line_1string
Example: "123 Example Road"
billing_address_line_2string
Example: "City District"
billing_postcodestring
Example: "EX4 4PL"
billing_countystring
Example: "Lancashire"
billing_countrystring
Example: "United Kingdom"
get_loginboolean
Example: true
curl -i -X POST \
  https://propello-cloud.redocly.app/_mock/openapi/v3/user/make-known/UID/ABC1234 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "john.smith@example.org",
    "UID": "ABC123",
    "first_name": "John",
    "last_name": "Smith",
    "company_name": "Smith Co Ltd.",
    "billing_phone": "+441234567890",
    "billing_email": "accounts@example.org",
    "billing_address_line_1": "123 Example Road",
    "billing_address_line_2": "City District",
    "billing_postcode": "EX4 4PL",
    "billing_county": "Lancashire",
    "billing_country": "United Kingdom",
    "get_login": true
  }'

Responses

OK

Bodyapplication/json
statusinteger
Example: 200
timestampstring
Example: "1970-01-30T00:00:00.000000Z"
dataobject
Response
application/json
{
  "status": 200,
  "timestamp": "1970-01-30T00:00:00.000000Z",
  "data": {
    "id": 987654,
    "UID": "ABC123",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.org",
    "created_at": "1970-01-30T00:00:00.000000Z",
    "login_url": "https://example.yourperx.com/auth-token/BkfEhiym5mvKYSrAp5iQ0YnRTB9mdo3r9kLXe6EuEhTPoAONLNIJ8TNzGerJVwgX"
  }
}

Group

Organisation Group Operations

Operations

Offer

Organisation Offer Operations

Operations
Copyright © Propello Cloud Ltd. 2024