Synchronising User Information

This details how to seed and synchronise new users and changes to users between Pepper's CRM and a 3rd party CRM

Seeding User Data

Before you can start synchronising user data, you need to seed your CRM with data from Pepper, or vice versa.

Downloading existing customer information from Pepper

Adding a file download method is on our roadmap and will be available in the future

To retrieve customer information, call the GET /users endpoint. This endpoint is paged so you will need to repeat the call until all pages have been returned.

We expect you will need to run this download only once. Avoid making scheduled downloads of all users to avoid hitting rate limits.

Make sure you ONLY include the information you need. Most use cases only need to include credentials.

For example

GET https://api.pepperhq.com/users?include=credentials
Authorization: Token <token-provided-by-pepper>
x-application-id: <merchant-code>
x-api-version: 8
Accept: application/json
Accept-Encoding: gzip, deflate

200 OK
{
  "items": [
    {
      ...
    }
  ],
  "page": {
      ...
  }
}

See Get Users API reference.

Uploading existing customer information into Pepper

The Pepper Ops team can organise loading existing customer records for a new merchant into the Pepper platform. This is a paid-for service. Please contact the Pepper Ops team.

Alternatively, you can use the POST /users to add new users into the Pepper platform.

Synchronising User Changes

Getting User Changes from Pepper

There are two approaches for retrieving new and changed users from Pepper:

1. Polling the GET /actions and processing events for user related events [PREFERRED].
2. Polling the GET /users endpoint with the updatedAfter query parameter to request any changes since the last time you requested.

1. Polling GET /actions

The GET /actions endpoint should be called on a regular schedule to receive notification of changes since the last call. A suitable schedule is every 5 minutes, or shorter if your responses require multiple pages to retrieve.

You should set query parameters for when.timestamp to a range starting after the last time you requested up to and including the current time. For example: when.timestamp.gt=2021-02-01T10:00:00.000Z & when.timestamp.lte=2021-02-01T10:05:00.000Z will return actions after 10 AM on Feb 1 up to and including 10.05 AM.

You should then process the response for the following events that are relevant for user record changes:

• USER_CREATED a new user has signed up
• USER_CHANGED a user record has changed
• USER_DELETED a user has been removed (GDPR request)
• USER_ACTIVATED a user has validated their login credential (eg email or phone)
• CREDENTIAL_VERIFIED (if needed) secondary credentials (eg email) has been verified

Other user related actions such as USER_ACTIVATION_RESENT do not need to be monitored.

You can limit the call to just these action types using the type query parameter.

Example call:

GET https://api.pepperhq.com/actions?when.timestamp.gt=2021-02-01T10:00:00.000Z&when.timestamp.lte=2021-02-01T10:05:00.000Z&type=USER_CREATED,USER_CHANGED,USER_DELETED,USER_ACTIVATED
Authorization: Token <token-provided-by-pepper>
x-application-id: <merchant-code>
x-api-version: 8
Accept: application/json
accept-encoding: gzip, deflate

200 OK
{
  "items": [
    {
      ...
    }
  ],
  "page": {
      ...
  }
}

See Get Actions API reference.

The bottom of this section includes examples of actions.

2. Polling GET /users

To see just new and changed user records, you can poll the GET /users endpoint with the updatedAfter parameter set.

You set the updatedAfter query parameter to the last time you requested GET /users.

Make sure you ONLY include the information you need. Most use cases only need to include credentials.

For example

GET https://api.pepperhq.com/users?include=credentials&updatedAfter=2021-02-17T09:06:03.715Z
Authorization: Token <token-provided-by-pepper>
x-application-id: <merchant-code>
x-api-version: 8
Accept: application/json
Accept-Encoding: gzip, deflate

200 OK
{
  "items": [
    {
      ...
    }
  ],
  "page": {
      ...
  }
}

See the Get Users API reference.

Saving User Changes to Pepper

You can add, change and remove users via the API.

Add User

Use the POST /users endpoint. See Create User.

Change User

Use the PUT /users/:userId endpoint. See Update User.

Remove User

This should be only used for processing GDPR user removal requests.

Use the DELETE /users/:userId endpoint. See Delete User.

Note: the user information is retained for data analytics, but all user identifying data is redacted in accordance with GDPR.

Action Examples

USER_CREATED

Use the context.user and metadata fields for relevant user info

{
    "_id" : "xxxx",
    "context" : {
        "tenant" : {
            "_id" : "xxxx",
            "title" : "The Grill"
        },
        "user" : {
            "_id" : "xxxx",
            "fullName" : "Tom Jones",
            "primaryPlatform" : "IOS"
        },
        "tags" : []
    },
    "tenantId" : "xxxx",
    "type" : "USER_CREATED",
    "source" : "API_SERVER",
    "version" : "0",
    "when" : {
        "timezone" : "America/Chicago",
        "timestamp" : "2021-03-05T02:32:10.218Z",
        "year" : 2021,
        "monthofyear" : 2,
        "weekofyear" : 10,
        "dayofmonth" : 4,
        "dayofweek" : 4,
        "daypart" : "EVENING"
    },
    "metadata" : {
        "username" : "+12220000000",
        "provider" : "MOBILE",
        "hasAgreedToShareData" : true,
        "hasAgreedToReceiveMarketing" : false
    },
    "environment" : "PRODUCTION"
}

USER_CHANGED

As per USER_CREATED, but the metadata field contains changed user records.

{
    "type" : "USER_CHANGED",
    "metadata" : {
        "favouriteLocations" : [ 
            "xxxxx", 
            "yyyyy"
        ]
    }
}

USER_ACTIVATED

As per USER_CREATED, but the metadata field contains the activated credential

{
    "type" : "USER_ACTIVATED",
    "metadata" : {
        "username" : "tomjones@emailme.com",
        "provider" : "EMAIL"
    }
}