Introduction

Authentication

In order to access the API, you will need to provide an access token to authenticate with the API server. That token will be required for all API requests.

You can acquire that token with the API endpoint described in the following section.

Once you have acquired the API token, it may be provided preferably via an HTTP header or in a query string parameter.

  • HTTP Header

    The following header should be used:

    Authorization: Bearer YOUR_ACCESS_TOKEN

  • Query String

    If you cannot set the access token in a header, it also may be passed in as part of the query string with the parameter access_token.

Get an access token

Arguments
  • grant_type

    required string

    OAuth2 grant type. Always use client_credentials.

  • client_id

    required string

    Your client id.

  • client_secret

    required string

    Your client secret.

  • scope

    required string

    Space-delimited list of permissions. The required permissions are documented for each API endpoint.

Returns

Returns a JSON object with the access_token field containing the requested Access Token.

The other fields are:

  • expires_in: The lifetime in seconds of the access token.
  • token_type: Always Bearer
Definition
POST /oauth/token
Example Request
POST /oauth/token HTTP/1.1
Host: https://YOUR_DOMAIN
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "scope": "read:users manage:users"
}
Example Response
{
  "access_token": "kGu...uLs",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Errors

ReachFive uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a parameter is invalid, etc.), and codes in the 5xx range indicate an error with ReachFive's servers (these are unexpected).

HTTP status code summary

Error CodeMeaning
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter, or invalid data
401 - UnauthorizedThe request requires authentication, or the credentials are invalid
404 - Not FoundThe requested resource doesn't exist.
500 - Internal Server ErrorThe server encountered an unexpected condition that prevented it from fulfilling the request.
501 - Not ImplementedThe server cannot fulfill the request because of missing or invalid account configuration.
503 - Service UnavailableThe server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

Error object

Attributes
  • error

    string

    A short string representing the type of error that occurred.

  • error_description

    string

    A human-readable text description of the error.

  • error_user_msg

    optional string

    The message to display to the user. The language of the message is based on the locale of the API request.

  • error_details

    optional array

    A list of sub-errors. Mostly used for form validation.

    Show child attributes
Example
{
  "error": "invalid_access_token",
  "error_description": "Access token invalid or expired"
}

Error list

ErrorDescription
invalid_requestThe request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
invalid_stateThe request is well-formed but the current state of resources prevent it from being fulfilled (e.g. trying to activate an already activated account).
invalid_grantThe provided authorization grant (e.g., authorization code, user credentials) or id token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client..
server_error500 HTTP response
temporarily_unavailable503 HTTP response
access_deniedThe user or the social provider (Facebook, Google...) denied the request
email_already_existsThe provided email already exists.
external_id_already_existsThe provided external id already exists.

Choosing fields

By default, not all fields of an object are returned when you make a query. You can choose the fields that you want returned with the fields query parameter. This is really useful for making your API calls more efficient and fast.

For example, the API call on the right will only return the id, name, and email of the user's profile.

Returns

Example Request
GET /api/v2/users/AVqvOB58Fg6nZfQ0ZqXt?fields=id,name,email
Example Response
{
  "id": "AVqvOB58Fg6nZfQ0ZqXt",
  "name": "John Doe",
  "email": "john.doe@example.com"
}

Filtering

Some endpoints support results filtering. For this purpose, you have to use the filter parameter.

The search is made of a series of terms which are composed of a field, an operator, and possibly a value:

`{field} {operator} {value?}`

If you have multiple terms, they must be separated by the AND operator (OR is not supported yet).

Equality operator

You can search for exact matches by using the equality operator ==.

Examples:

  • email == "john.doe@example.com"
  • age == 30
  • email_verified == true

Inclusion

You can filter a field by multiple values with the IN operator. When applied to a collection, there must be at least one matching item.

Example:

identities.provider IN ("facebook", "google")

Exclusion

You can filter a field by multiple values with the NOT IN operator. When applied to a collection, all items must not match.

Example:

identities.provider NOT IN ("facebook", "google")

Existence

You can check for the presence of a field using the EXISTS operator. It checks whether a certain field is defined (i.e. it has any value).

If the field is not defined, it will not be present in the JSON payload and the operator will consider it non-existent.

Example:

phone_number EXISTS

Absence

You can check for the absence of a field using the MISSING operator. It checks whether a certain field is not defined (i.e. it has no value).

Example:

given_name MISSING

Ranges

Four range operators are available. They are applicable to date and number fields:

  • <: Less than.
  • <=: Less than or equal to.
  • >: Greater than.
  • >= Greater than or equal to.

Examples:

  • age >= 30 AND age < 40
  • last_login >= "2018-01-01"

Text search

You can search for partial matching in your text fields with the following operators:

  • CONTAINS: Checks if the field contains some text
  • STARTS WITH: Checks if the field starts with a specific text
  • END WITH: Checks if the field ends with a specific text

Examples:

  • email CONTAINS "john"
  • email ENDS WITH "@gmail.com"
  • email STARTS WITH "john.doe"

Returns

Example Request
GET /api/v2/users?filter=age%20%3E%3D%2030%20AND%20age%20%3C%2040%20AND%20gender%20%3D%3D%20%22female%22&fields=id,name
Example Response
{
  "total": 58,
  "items": [
    {
      "id": "AVqvOB58Fg6nZfQ0ZqXt",
      "name": "Elizabeth Smith"
    },
    {
      "id": "AWYMQlcj302KtelmOfp1",
      "name": "Julia Carter"
    },
    ...
  ]
}

Users

Create user

Create the specified user by setting the values of the object's properties passed. One of those attributes is mandatory:

  • email
  • phone_number

These are the user's attributes that can be setted at the root level:

  • external_id
  • email
  • email_verified
  • phone_number
  • phone_number_verified
  • given_name
  • middle_name
  • family_name
  • name
  • nickname
  • username
  • birthdate
  • gender
  • addresses
  • phone_number
  • picture
  • company
  • custom_fields
  • consents

Scope:  manage:users

Arguments
  • fields

    string

    Fields to retrieve

Returns

Returns the user object if the creation succeeded. Returns an error if create parameters are invalid (e.g. specifying an invalid birth date).

Definition
POST /api/v2/users
Example Request
POST /api/v2/users?fields=id,name,email,birthdate HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "name": "John Doe",
  "email": "johndoe@example.com",
  "birthdate": "1981-10-13"
}
Example Response
{
  "id": "AVqvOB58Fg6nZfQ0ZqXt",
  "name": "John Doe",
  "email": "johndoe@example.com",
  "birthdate": "1981-10-13"
}

Get user

Retrieves the details of an existing customer.

Scope:  read:users

Arguments
  • user_id

    required string

    Id of the user to retrieve.

  • fields

    string

    Fields to retrieve

Returns

Returns the user object. Returns an error if parameters are invalid (e.g. specifying an invalid user id).

Definition
GET /api/v2/users/{user_id}
Example Request
GET /api/v2/users/AVqvOB58Fg6nZfQ0ZqXt?fields=email,gender,given_name,family_name,birthdate HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
{
  "email": "johndoe@example.com",
  "gender": "male",
  "given_name": "John",
  "family_name": "Doe",
  "birthdate": "1970-01-01"
}

Search users

Retrieves a list of users.

Scope:  read:users

Arguments
  • filter

    string

    Search criteria. More informations here.

  • fields

    string

    Fields to retrieve.

  • page

    integer

    Page number. One based. Defaults to 1.

  • count

    integer

    Amount of items per page. Defaults to 20.

  • sort

    string

    Field to use for sorting. Use field:order where order is asc for ascending and desc for descending. For example created_at:desc.

Returns

Definition
GET /api/v2/users
Example Request
GET /api/v2/users?filter=age%20%3E%2030%20AND%20gender%20%3D%3D%20%22male%22&fields=id,name,email,gender,birthdate HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
{
  "total": 1,
  "items": [
    {
      "id": "AVs03HoxJSTFLRxVXhri",
      "name": "John Doe",
      "email": "johndoe@example.com",
      "gender": "male",
      "birthdate": "1978-09-25"
    }
  ]
}

Update user

Updates the specified user by setting the values of the object's properties passed. Any root properties (or custom fields) not provided will be left unchanged. These are the user's attributes that can be updated at the root level:

  • external_id
  • email
  • email_verified
  • phone_number
  • phone_number_verified
  • given_name
  • middle_name
  • family_name
  • name
  • nickname
  • username
  • birthdate
  • gender
  • addresses
  • phone_number
  • picture
  • company
  • custom_fields
  • consents

Scope:  manage:users

Arguments
  • user_id

    required string

    Id of the user to retrieve.

  • fields

    string

    Fields to retrieve

Returns

Returns the user object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid birth date).

Definition
PUT /api/v2/users/{user_id}
Example Request
PUT /api/v2/users/AVqvOB58Fg6nZfQ0ZqXt?fields=id,name,email,birthdate HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "birthdate": "1981-10-13",
  "nickname": "Johnny"
}
Example Response
{
  "id": "AVqvOB58Fg6nZfQ0ZqXt",
  "name": "John Doe",
  "email": "johndoe@example.com",
  "birthdate": "1981-10-13"
}

Delete user

Delete user and all related data definitely.

Scope:  manage:users

Arguments
  • user_id

    required string

    Id of the user to delete.

Definition
DELETE /api/v2/users/{user_id}
Example Request
DELETE /api/v2/users/AVqvOB58Fg6nZfQ0ZqXt HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN

Merge two users

Merge two users' profiles.

Scope:  manage:users

Arguments
  • user_id1

    required string

    Id of the user to update. This id is kept in the new user's profile.

  • user_id2

    string

    Id of the user to merge.

  • fields

    string

    Fields to retrieve in the response.

Returns

Returns the user's profile resulting from the merge if the call succeeded, or an error otherwise.

Definition
POST /api/v2/users/{user_id1}/merge/{user_id2}
Example Request
POST /api/v2/users/AVqvOB58Fg6nZfQ0ZqXt/merge/AVs03HoxJSTFLRxVXhri?fields=id,given_name,family_name,email,birthdate HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
{
  "id": "AVs03HoxJSTFLRxVXhri",
  "given_name": "John",
  "family_name": "Doe",
  "email": "johndoe@example.com",
  "birthdate": "1981-10-13"
}

Remove user identity

Remove user's identity. On success, the endpoint returns the new user's profile.

Scope:  manage:users

Arguments
  • user_id

    required string

    Id of the user.

  • identity_unique_id

    required string

    Unique id of the identity to remove. See unique_id field of Identity object.

  • fields

    string

    Fields to retrieve in the response.

Definition
DELETE /api/v2/users/{user_id}/identities/{identity_unique_id}
Example Request
DELETE /api/v2/users/AVqvOB58Fg6nZfQ0ZqXt/identities/facebook:121146661725694 HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN

Remove user provider

Remove all user's identities coming from the specified provider. On success, the endpoint returns the new user's profile.

Scope:  manage:users

Arguments
  • user_id

    required string

    Id of the user.

  • provider

    required string

    Id of the provider to remove. See provider field of Identity object.

  • fields

    string

    Fields to retrieve in the response.

Definition
DELETE /api/v2/users/{user_id}/providers/{provider}
Example Request
DELETE /api/v2/users/AVqvOB58Fg6nZfQ0ZqXt/providers/facebook HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN

Export users as CSV

Export CSV file containing user data.

Scope:  export:users

Arguments
  • fields

    required string

    Fields to retrieve.

  • filter

    string

    Search criteria. More informations here.

  • format

    string

    Must be csv.

Returns

Definition
GET /api/v2/users/export?format=csv
Example Request
GET /api/v2/users/export?filter=gender%20%3D%3D%20%22male%22&fields=id,name,email,gender,birthdate&format=csv HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
id;name;email;gender;birthdate
"AVs03HoxJSTFLRxVXhri";"John Doe";"johndoe@example.com";"male";"1978-09-25"
"AVrrKMv4NH_LdFnfTRxK";"Bob Doe";"bobdoe@example.com";"male";"1989-03-12"

Export users as JSON

Export users file with Newline Delimited JSON format.

Scope:  export:users

Arguments
  • fields

    required string

    Fields to retrieve.

  • filter

    string

    Search criteria. More informations here.

  • format

    string

    Must be json.

Returns

Definition
GET /api/v2/users/export?format=json
Example Request
GET /api/v2/users/export?fields=id,name,email&filter=gender%20%3D%3D%20%22male%22&format=json HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
{"id":"AVs03HoxJSTFLRxVXhri","name":"John Doe","email":"johndoe@example.com"}
{"id":"AVrrKMv4NH_LdFnfTRxK","name":"Bob Doe","email":"bobdoe@example.com"}

Send a "verify email address" email

Sends an email to a user that asks them to click a link to verify their email address.

Scope:  manage:users

Arguments
  • user_id

    required string

    User's id.

Definition
POST /api/v2/users/{user_id}/verify-email
Example Request
POST /api/v2/users/AVqvOB58Fg6nZfQ0ZqXt/verify-email HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN

User object

Attributes
  • id

    string

    ReachFive's user id.

  • external_id

    string

    User's external id.

  • name

    string

    User's full name.

  • given_name

    string

    Given name(s) or first name(s).

  • family_name

    string

    Surname(s) or last name(s).

  • middle_name

    string

    Middle name(s).

  • nickname

    string

    Casual name that may or may not be the same as the given_name.

  • profile

    string

    URL of one of the user's profile page (generally a social provider's page).

  • picture

    string

    URL of one of the user's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file).

  • email

    string

    User's primary email address.

  • email_verified

    string

    true if the user's email address has been verified.

  • emails

    object

    User's email list

    Show child attributes
  • phone_number

    string

    User's primary telephone number.

  • phone_number_verified

    string

    true if the user's phone number has been verified.

  • gender

    string

    User's gender. Allowed values are female, male or other.

  • birthdate

    date

    User's birthday, represented as an ISO 8601 YYYY-MM-DD format.

  • age

    integer

    User's age computed from birth date.

  • company

    string

    User's company name.

  • likes_count

    integer

    Number of facebook pages liked by the user.

  • addresses

    array of object

    User's postal addresses.

    Show child attributes
  • identities

    array of object

    List of user's provider identities.

    Show child attributes
  • has_password

    boolean

    true if the user has a password.

  • custom_fields

    object

    Object containing user's custom fields.

  • consents

    object

    Object containing user's consents.

    Show child attributes
  • created_at

    datetime

    Date when the user was created.

  • updated_at

    datetime

    Date when the user was last updated.

  • first_login

    datetime

    Date of the user's first login.

  • last_login

    datetime

    Date of the user's last login.

  • logins_count

    integer

    Number of logins for this user.

  • last_login_type

    string

    Name of the authentication type used when user last logged in. e.g. facebook, google, password...

  • friends

    array of object

    List of user's friends also linked to the same ReachFive account

    Show child attributes
  • origins

    array of strings

    List of origins.

  • facebook_ids_for_pages

    array of objects

    List of page scoped facebook user ids.

    Show child attributes
Example
{
  "id": "AVqvOB58Fg6nZfQ0ZqXt",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "username": "jdoe",
  "nickname": "Johnny",
  "birthdate": "1983-11-13",
  "age": 33,
  "email": "john.doe@example.com",
  "email_verified": true,
  "emails": {
    "verified": [
      "john.doe@example.com"
    ],
    "unverified": [
      "other@example.com"
    ]
  },
  "gender": "male",
  "phone_number": "+33612345678",
  "phone_number_verified": false,
  "picture": "https://graph.facebook.com/10154500298019865/picture",
  "profile": "https://www.facebook.com/app_scoped_user_id/10154500298019865/",
  "addresses": [
    {
      "default": true,
      "address_type": "billing",
      "street_address": "10 rue Chaptal",
      "locality": "Paris",
      "postal_code": "75009",
      "region": "Île-de-France",
      "country": "France"
    }
  ],
  "likes_count": 67,
  "created_at": "2017-03-08T18:39:35.026Z",
  "updated_at": "2018-08-12T12:54:09.631Z",
  "first_login": "2017-03-08T18:39:35.026Z",
  "last_login": "2018-08-12T12:54:09.631Z",
  "logins_count": 53,
  "origins": [
    "website",
    "game"
  ],
  "last_login_type": "facebook",
  "custom_fields": {
    "loyalty_card_number": "19872359235"
  },
  "consents": {
    "newsletter": {
        "consent_type": "opt-in"
        "granted": true,
        "date": "2018-05-25T15:41:09.671Z"
      }
  },
  "facebook_ids_for_pages": [
    {
      "user_id": "649145309042062",
      "page_id": "931332113682072"
    }
  ]
}

Facebook likes

Search likes

Search and retrieve a list of facebook likes.

Scope:  read:facebook-likes

Arguments
  • filter

    string

    Search criteria. More informations here.

  • fields

    string

    Fields to retrieve.

  • page

    integer

    Page number. One based. Defaults to 1.

  • count

    integer

    Amount of items per page. Defaults to 20.

  • sort

    string

    Field to use for sorting. Use field:order where order is asc for ascending and desc for descending. For example created_at:desc.

Returns

Definition
GET /api/v2/facebook-likes
Example Request
GET /api/v2/facebook-likes?filter=page_id%20%3D%3D%20%22625041464209975%22&fields=user_id,page_id,name,category,created_at HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
{
  "total": 2,
  "items": [
    {
      "user_id": "AVs03HoxJSTFLRxVXhri",
      "page_id": "625041464209975",
      "name": "ReachFive",
      "category": "SOFTWARE COMPANY",
      "created_at": "2017-03-08T18:39:35.026Z"
    },
    {
      "user_id": "AVqvOB58Fg6nZfQ0ZqXt",
      "page_id": "625041464209975",
      "name": "ReachFive",
      "category": "SOFTWARE COMPANY",
      "created_at": "2016-11-27T11:35:28.725Z"
    }
  ]
}

Search user's likes

Search and retrieve user's facebook likes.

Scope:  read:facebook-likes

Arguments
  • filter

    string

    Search criteria. More informations here.

  • fields

    string

    Fields to retrieve.

  • page

    integer

    Page number. One based. Defaults to 1.

  • count

    integer

    Amount of items per page. Defaults to 20.

  • sort

    string

    Field to use for sorting. Use field:order where order is asc for ascending and desc for descending. For example created_at:desc.

Returns

Definition
GET /api/v2/users/{user_id}/facebook-likes
Example Request
GET /api/v2/users/AVs03HoxJSTFLRxVXhri/facebook-likes?filter=created_at%20%3E%3D%20%222017-08-01%22&fields=page_id,name,category,created_at HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
{
  "total": 2,
  "items": [
    {
      "page_id": "625041464209975",
      "name": "ReachFive",
      "category": "SOFTWARE COMPANY",
      "created_at": "2017-08-08T15:28:53.729Z"
    },
    {
      "page_id": "299643823431682",
      "name": "Gad Elmaleh",
      "category": "ARTIST",
      "created_at": "2017-09-16T22:47:22.925Z"
    }
  ]
}

Export likes as CSV

Export CSV file containing facebook likes.

Scope:  export:facebook-likes

Arguments
  • filter

    string

    Search criteria. More informations here.

  • fields

    string

    Fields to retrieve.

  • format

    string

    Must be csv.

Returns

Definition
GET /api/v2/facebook-likes?format=csv
Example Request
GET /api/v2/facebook-likes/export?format=csv&fields=user_id,page_id,name,category,created_at HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
user_id;page_id;name;category;created_at
AVs03HoxJSTFLRxVXhri;625041464209975;ReachFive;SOFTWARE COMPANY;08/03/2017
AVqvOB58Fg6nZfQ0ZqXt;625041464209975;ReachFive;SOFTWARE COMPANY;03/05/2017
AVqvOB58Fg6nZfQ0ZqXt;299643823431682;Gad Elmaleh;ARTIST;16/09/2017

Export likes as JSON

Export facebook likes file with Newline Delimited JSON format.

Scope:  export:facebook-likes

Arguments
  • filter

    string

    Search criteria. More informations here.

  • fields

    string

    Fields to retrieve.

  • format

    string

    Must be json.

Returns

Definition
GET /api/v2/facebook-likes?format=json
Example Request
GET /api/v2/facebook-likes/export?format=json&fields=user_id,page_id,name,category,created_at HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
{"user_id": "AVs03HoxJSTFLRxVXhri","page_id": "625041464209975","name": "ReachFive","category": "SOFTWARE COMPANY","created_at": "2017-03-08T18:39:35.026Z"}
{"user_id": "AVs03HoxJSTFLRxVXhri","page_id": "299643823431682","name": "Gad Elmaleh","category": "ARTIST","created_at": "2017-09-16T22:47:22.925Z"}
{"user_id": "AVqvOB58Fg6nZfQ0ZqXt","page_id": "625041464209975","name": "ReachFive","category": "SOFTWARE COMPANY","created_at": "2016-11-27T11:35:28.725Z"}

Facebook like object

Attributes
  • user_id

    string

    User id.

  • page_id

    string

    Facebook page id.

  • name

    string

    Facebook page name.

  • category

    string

    Facebook page category.

  • created_at

    datetime

    Time the user liked the page.

Example
{
  "user_id": "AVs03HoxJSTFLRxVXhri",
  "page_id": "625041464209975",
  "name": "ReachFive",
  "category": "SOFTWARE COMPANY",
  "created_at": "2017-03-08T18:39:35.026Z"
}

User events

Search events

Search and retrieve a list of user events.

Scope:  read:user-events

Arguments
  • filter

    string

    Search criteria. More informations here.

  • fields

    string

    Fields to retrieve.

  • page

    integer

    Page number. One based. Defaults to 1.

  • count

    integer

    Amount of items per page. Defaults to 20.

  • sort

    string

    Field to use for sorting. Use field:order where order is asc for ascending and desc for descending. For example date:desc.

Returns

Definition
GET /api/v2/user-events
Example Request
GET /api/v2/user-events?filter=type%20%3D%3D%20%22login%22&fields=id,user_id,type,date,device,client_id,auth_type,origin,user_agent HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
{
  "total": 2,
  "items": [
    {
      "id": "AWUTwp6tD6KwGSiAAIKv",
      "type": "login",
      "user_id": "AWUTworxD6KwGSiAAIKj",
      "date": "2018-08-07T09:40:46.177Z",
      "client_id": "sg48CdAYohRPeRWZ9j1H",
      "device": "desktop",
      "auth_type": "password",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36"
    },
    {
      "id": "AWUTwpwWD6KwGSiAAIKu",
      "type": "login",
      "user_id": "AWUTwopED6KwGSiAAIKi",
      "date": "2018-08-07T09:40:45.192Z",
      "client_id": "sg48CdAYohRPeRWZ9j1H",
      "device": "mobile_web",
      "auth_type": "password",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_3 like Mac OS X) AppleWebKit/603.3.8 (KHTML, like Gecko) Mobile/14G60"
    }
  ]
}

Search events by user

Search and retrieve a list of user events by user id.

Scope:  read:user-events

Arguments
  • filter

    string

    Search criteria. More informations here.

  • fields

    string

    Fields to retrieve.

  • page

    integer

    Page number. One based. Defaults to 1.

  • count

    integer

    Amount of items per page. Defaults to 20.

  • sort

    string

    Field to use for sorting. Use field:order where order is asc for ascending and desc for descending. For example date:desc.

Returns

Definition
GET /api/v2/users/{user_id}/events
Example Request
GET /api/v2/users/AWUTz0JBD6KwGSiAAIMH/events?fields=id,user_id,type,date,device,client_id,auth_type,origin,user_agent HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
{
  "total": 2,
  "items": [
    {
      "id": "AWUTz06ZD6KwGSiAAIMR",
      "type": "login",
      "user_id": "AWUTz0JBD6KwGSiAAIMH",
      "date": "2018-08-07T09:54:34.183Z",
      "client_id": "sg48CdAYohRPeRWZ9j1H",
      "device": "desktop",
      "auth_type": "facebook",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_3 like Mac OS X) AppleWebKit/603.3.8 (KHTML, like Gecko) Mobile/14G60"
    },
    {
      "id": "AWUTz0naD6KwGSiAAIMN",
      "type": "signup",
      "user_id": "AWUTz0JBD6KwGSiAAIMH",
      "date": "2018-08-07T09:54:34.183Z",
      "client_id": "sg48CdAYohRPeRWZ9j1H",
      "device": "desktop",
      "auth_type": "facebook",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_3 like Mac OS X) AppleWebKit/603.3.8 (KHTML, like Gecko) Mobile/14G60"
    }
  ]
}

User event object

Attributes
  • id

    string

    User event id.

  • User event type.

  • user_id

    string

    User's id.

  • date

    datetime

    Time of created event.

  • client_id

    string

    Client id used.

  • device

    string

    User's device.

  • auth_type

    string

    Authentication used.

  • origin

    string

    Origin.

  • ip

    string

    User's IP adress.

  • user_agent

    string

    Web user agent.

Example
{
  "id": "AWUTz0naD6KwGSiAAIMN",
  "type": "signup",
  "user_id": "AWUTz0JBD6KwGSiAAIMH",
  "date": "2018-08-07T09:54:34.183Z",
  "client_id": "sg48CdAYohRPeRWZ9j1H",
  "device": "desktop",
  "auth_type": "facebook",
  "origin": "origin",
  "ip": "127.0.0.1",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_3 like Mac OS X) AppleWebKit/603.3.8 (KHTML, like Gecko) Mobile/14G60"
}

User event type

  • login. Emitted after a successful authentication.
  • signup. Emitted after a successful signup.
  • unlink. Emitted after a successful unlink identity.
  • email_updated. Emitted after a successful email update.
  • email_verified. Emitted after a successful email verification.
  • phone_number_updated. Emitted after a successful phone number update.
  • phone_number_verified. Emitted after a successful phone number verification.
  • password_reset_requested. Emitted after a successful password reset request.
  • password_updated. Emitted after a successful password update.
  • otp_sent. Emitted after a successful one time password send.
  • user_updated. Emitted after a successful user update.
  • user_deleted. Emitted after a successful user deletion.