Collect API

Overview

The Collect API enables you to send Thing and User data from your server to Copilot so that it appears in the Copilot Web Portal and enables engagement functionality.

The Report endpoint sends an Events array containing one or more events. The following kinds of events can be sent:

• Thing events
• Custom events
• Other Misc. events

Common Collect API Fields

Each event in the Events array may contain the following common fields:

type

This is a mandatory field that defines the type of event. For example, user_created. Each type of event may have different mandatory and optional fields.

payload

Contains the primary content to be transferred by an event. The payload field contains one or more fields (some are mandatory and some optional). These fields are described in the tables below.

user_id and thing_id

Practices for your unique identifier for a User or for a Thing:

• Each User identifier must be the same user identifier that is sent from a mobile device’s application using the Copilot SDK.

• Each Thing identifier must be the same physical device identifier that is sent from a mobile device’s application using the Copilot SDK.

• Unique identifiers for Users and Things are required when reporting events so that the activity described in the event can be attributed to the relevant User or Thing.

event_id

A unique identifier that you provide with each event sent to Copilot Report. This ID enables tracking of the event for future reference, if needed. This event_id is particularly important when an invalid event message is returned by Copilot Report. This unique event identifier enables you to analyze the problem and resend the event to Copilot, if necessary.

timestamp

UNIX EPOCH timestamps in milliseconds (starting from 01/01/1970 UTC).

Field validation constraints on the timestamp field:

• Must be in milliseconds.
• Must be during the last 30 days.
• Cannot be a future date.

General Field Value Constraints

For the following fields ‒ event_id, user_id, thing_id, first_name, last_name and email:

• Maximum String Length ‒ 50
• Supported Characters ‒ Supports all Latin extended, excluding: < > { } [ ] - ; # & ( ) $ | ^ \ / , . * + = : % ! ~ "

For the following fields ‒ status_name, status_value and sub_type:

• Maximum String Length ‒ 50

Request

• End point : https://report.<YOUR_ENVIRONMENT>.bycopilot.com/v2/collect
• HTTP Method : POST
• HTTP Headers:
  • Content-Type : application/json
  • Authorization: Basic $YOUR_AUTH_DATA_HERE$
• Example of HTTP Request:

  {
    "events": [
      {
        "type": "user_created",
        "event_id": "5139f606-a47b-45b9-8fa2-20d1576950be",
        "timestamp": 1559570628993,
        "payload": {
          "email": "juanita.pagac43@mailinator.com",
          "first_name": "Juanita",
          "last_name": "Pagac",
          "user_id": "325ca496-afe8-4f44-bd37-b0dc90bdfdea",
          "utc_offset": "-0500"
        }
      }
    ]
  }

Response

Success response

Success:

{
  "invalid_events": []
}

Error response

Failure (in case of missing a mandatory property):

• Case of missing "timestamp" property:

{
  "invalid_events": [
    {
      "event_id": "f6a1c1d2-7932-414b-a480-31ea08d97200",
      "index": 0,
      "error": "Event missing field: timestamp."
    }
  ]
}

• Case of unrecognized event type:

{
  "invalid_events": [
    {
      "event_id": "d459b177-9afc-498c-984e-4ba6fb0aa249",
      "index": 0,
      "error": "Event type not recognized."
    }
  ]
}

Error response general structure

{
    "reason": enum,
    "error_message": string
}

Possible errors:

• HTTP code: 405

{
    "reason": "COMMON.INVALID_METHOD"
}

• HTTP code: 400

{
    "reason": "COMMON.REQUEST_VALIDATION",
    "error_message": "Request missing field: 'events'."
}

• HTTP code: 400

{
    "reason": "COMMON.REQUEST_VALIDATION",
    "error_message": "The field 'events' must be an array."
}

• HTTP code: 400

{
    "reason": "COMMON.REQUEST_VALIDATION",
    "error_message": "The field 'events' must be an array containing between 1-200."
}

• HTTP code: 400

{
    "reason": "COMMON.REQUEST_VALIDATION",
    "error_message": "The header 'content-type' must be 'application/json'."
}

• Not bearer or basic token - HTTP code: 401

{
    "reason": "AUTH.UNAUTHORIZED"
}

• Invalid token - HTTP code: 401

{
    "reason": "AUTH.UNAUTHORIZED"
}

• Token expired - HTTP code: 401

{
    "reason": "AUTH.UNAUTHORIZED"
}

• Invalid user role - HTTP code: 403

{
    "reason": "AUTH.INVALID_PERMISSIONS"
}

Success response structure:

HTTP code: 200

{
  "Invalid_events": Array<InvalidEvent>
}

• Invalid event structure:

If event id exists:

{
    "event_id": string,
    "index": number, // index in the original array
    "error": string
}

If event id doesn’t exists:

{
    "index": number, // index in the original array
    "error": string
}

Error handling

Possible errors due to invalid events:

• "Event missing field: {field_name}"

• "Payload missing field: {field_name}"

• "Payload has unknown fields. (note: {field_name})"

• "Payload should not have more than 20 keys."

• "Payload must be an object."

• "Event structure is invalid."

• "Event type not recognized."

• "Event timestamp must be a number. (note: timestamp must be in ms)"

• "Event timestamp must be a positive number. (note: timestamp must be in ms)"

• "Event timestamp invalid. (note: timestamp must be in ms)"

• "Event timestamp cannot be more than 30 days ago. (note: timestamp must be in ms)"

• "Event timestamp cannot be in the future. (note: timestamp must be in ms)"

• "status_date must be a number. (note: timestamp must be in ms)"

• "status_date must be a positive number. (note: timestamp must be in ms)"

• "status_date invalid. (note: timestamp must be in ms)"

• "Event cannot be null."

• "Event must be an object."

• "{field_name} contains invalid characters. (note: specials characters are limited to: [':', '-', '.', '_', '+', '@'])"

• "{field_name} length invalid. (note: 0-50)"

• "{field_name} must be valid string."

Field validation

Field name	Valid string	Valid string length	Valid character	Valid timestamp
thing_id	V	V	V	X
user_id	V	V	V	X
firmware_version	V	X	X	X
model	V	X	X	X
status_key	V	V	X	X
status_value	V	V	X	X
status_date	X	X	X	V
first_name	V	V	V	X
last_name	V	V	V	X
email	V	V	V	X
subtype	V	V	X	X
utc_offset	V	V	V	X