Users

External User Identifiers

As a convenience to API integrators, who may want to synchronize Record360 Users with their own user database, each User has an external_id field, which may be set to whatever identifier string the integrator uses to identify their users. The Record360 User API can then identify users by this this external ID (see below). It is entirely optional, and has no other function, but must be unique within the integrator’s users.

Specifying Users

Each endpoint that takes a User identifier (i.e. show, update, and destroy) accepts one of three forms: * The Record360 numeric User ID, as returned by the authenticate and show endpoints (e.g. 42). * self, which refers to the user currently making the request * An external user ID, prefaced with an underscore (e.g. _abcxyz123)

>>>

POST /api/users/authenticate
Authenticate as a particular User

Examples

$ curl -i \
  -H 'Accept: application/json; version=1' \
  -X POST \
  -H 'Content-type: application/json' \
  -d '{"user": { "username": "[email protected]", "password": "5up3r53kr37" }}' \
  https://api.record360.com/api/users/authenticate

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate

{
  "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIyIiwiaWF0IjoxNDY0MDQxODAzfQ.F33A91GOdYvXfe5fo-Sq3mL-dVGwCyeevd5sceuCLko",
  "user": {
    "id": "42",
    "username": "[email protected]",
    "first_name": "Some",
    "last_name": "User",
    "phone_number": "366.555.1570 x78744",
    "role": "user",
    "external_id": "s_user42",
    "created_at": "2016-05-23T22:16:43.000Z",
    "updated_at": "2016-05-23T22:16:43.000Z",
    "location": {
      "id": "89",
      "name": "Main Office",
      "address1": "4726 Thackeray Pl NE",
      "address2": "Suite 405",
      "city": "Seattle",
      "state": "WA",
      "zipcode": "98105",
      "timezone": "PST",
      "created_at": "2014-04-01T19:00:00.000Z",
      "updated_at": "2016-04-14T21:46:56.000Z",
      "workflow": { ... }
    }
  }
}

Params

Param name Description
user
required

Validations:

  • Must be a Hash
user[username]
required

User’s login or email address

Validations:

  • Must be a String
user[password]
required

User’s password

Validations:

  • Must be a String
>>>

GET /api/users/uploads/:file_id
Upload or verify a media file

GET /api/users/uploads/:nonce/:file_id
Upload or verify a media file

This endpoint provides a method to upload media files, which may then be referenced in other API endpoints. To add a media file:

  1. Call this endpoint, passing a unique file_id chosen by the client.
  2. The response will include an upload_url. Upload the media file to that URL using a standard HTTP PUT request.
  3. Reference the uploaded file by ID in other API endpoints (e.g. Transaction Create endpoint).

Behavior

  • For an unknown media file, responds with an URL for the client to upload to (upload_url).
  • For an existing media file, responds with the content type and size, as well as the upload URL (for the client to resume incomplete uploads).
  • For an media file that’s part of a completed Transaction, not upload URL is returned.
  • Media files are referenced in other API endpoints (e.g. the Transaction Create endpoint) by file ID.

Examples

$ curl -i \
  -H 'Accept: application/json; version=1' \
  -H "Authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjQyLCJpYXQiOjE0NjM2OTQ4MjN9.k48v-R-un93KdIXqp9Zi12JOGJCu8uibtrWjscFCTqc" \
  https://api.record360.com/api/users/uploads/new_file_42

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate

{
  "id": "new_file_42",
  "upload_url": "https://r360-uploads.s3.amazonaws.com/users/42/new_file_42?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIL3TVJJCFDZ7H5SA%2F20160628%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20160628T212443Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=cb91ba9307cbad975cc08495bce3d9113402948f1b67703ff20c58bb58bb090d"
}

$ curl -i \
  -H 'Accept: application/json; version=1' \
  -H "Authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjQyLCJpYXQiOjE0NjM2OTQ4MjN9.k48v-R-un93KdIXqp9Zi12JOGJCu8uibtrWjscFCTqc" \
  https://api.record360.com/api/users/uploads/existing_file_77

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate

{
  "id": "existing_file_77",
  "upload_url": "https://r360-uploads.s3.amazonaws.com/users/42/existing_file_77?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIL3TVJJCFDZ7H5SA%2F20160628%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20160628T212443Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=cb91ba9307cbad975cc08495bce3d9113402948f1b67703ff20c58bb58bb090d",
  "type": "image/png",
  "size": 42678
}

Params

Param name Description
file_id
required

File ID, must be unique to the user

Validations:

  • Must be a String
>>>

GET /api/users
Index of all Users within a company (manager only)

Examples

$ curl -i \
  -H "Accept: application/json; version=1" \
  -H "Authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjQyLCJpYXQiOjE0NjM2OTQ4MjN9.k48v-R-un93KdIXqp9Zi12JOGJCu8uibtrWjscFCTqc" \
  "https://api.record360.com/api/users?after_id=41&limit=2"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate

{
  "users": [
    {
      "id": "42",
      "username": "[email protected]",
      "first_name": "Some",
      "last_name": "User",
      "phone_number": "366.555.1570 x78744",
      "external_id": "s_user42",
      "location": { "id": 89, "name": "Main Office" },
      "created_at": "2016-05-23T22:16:43.000Z",
      "updated_at": "2016-05-23T22:16:43.000Z"
    },
    {
      "id": "43",
      "username": "[email protected]",
      ...
    }
    ...
  ],
  "links": {
    "prev": "https://api.record360.com/api/users?before_id=42&limit=2",
    "next": "https://api.record360.com/api/users?after_id=43&limit=2"
  }
}

Params

Param name Description
before_id
optional

Return Users before the specified ID

Validations:

  • Must be a String
after_id
optional

Return Users after the specified ID

Validations:

  • Must be a String
limit
optional

Limit the number of Users to return (max: 50)

Validations:

  • Must be a number.
>>>

GET /api/users/:id
Show a particular User (manager only for other users)

Examples

$ curl -i \
  -H "Accept: application/json; version=1" \
  -H "Authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjQyLCJpYXQiOjE0NjM2OTQ4MjN9.k48v-R-un93KdIXqp9Zi12JOGJCu8uibtrWjscFCTqc" \
  https://api.record360.com/api/users/42

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate

{
  "user": {
    "id": "42",
    "username": "[email protected]",
    "first_name": "Some",
    "last_name": "User",
    "phone_number": "366.555.1570 x78744",
    "role": "user",
    "external_id": "s_user42",
    "created_at": "2016-05-23T22:16:43.000Z",
    "updated_at": "2016-05-23T22:16:43.000Z",
    "location": {
      "id": "89",
      "name": "Main Office",
      "address1": "4726 Thackeray Pl NE",
      "address2": "Suite 405",
      "city": "Seattle",
      "state": "WA",
      "zipcode": "98105",
      "timezone": "PST",
      "created_at": "2014-04-01T19:00:00.000Z",
      "updated_at": "2016-04-14T21:46:56.000Z",
      "workflow": { ... }
    }
  }
}

Params

Param name Description
id
required

User ID, _externalid, or “self”

Validations:

  • Must be a String
>>>

POST /api/users
Create a new User

Organizational users

Request must be authenticated with a User having the manager role, and a location_id may be specified. HTTP response is the same as for show action.

Examples

$ curl -i \
  -H "Accept: application/json; version=1" \
  -X POST \
  -H 'Content-type: application/json' \
  -d '{"user": { "username": "[email protected]", "password": "5up3r53kr37", "first_name": "John", "last_name": "Random" }}' \
  https://api.record360.com/api/users

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate

{
  "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIyIiwiaWF0IjoxNDY0MDQxODAzfQ.F33A91GOdYvXfe5fo-Sq3mL-dVGwCyeevd5sceuCLko",
  "user": {
    "id": "42",
    "username": "[email protected]",
    "first_name": "John",
    "last_name": "Random",
    "role": "user",
    "created_at": "2016-05-23T22:16:43.000Z",
    "updated_at": "2016-05-23T22:16:43.000Z",
    "location": { ... }
  }
}

Params

Param name Description
user
required

User attributes

Validations:

  • Must be a Hash
user[username]
required

Username or email address, must be globally unique

Validations:

  • Must be a String
user[password]
required

Password

Validations:

  • Must be a String
user[first_name]
required

First name

Validations:

  • Must be a String
user[last_name]
required

Last name

Validations:

  • Must be a String
user[phone_number]
optional

Phone number

Validations:

  • Must be a String
user[active]
optional , nil allowed

Account enabled? (manager only)

Validations:

  • Must be one of: true, false, 1, 0.
user[location_id]
optional , nil allowed

Location ID (manager only)

Validations:

  • Must be a String
user[external_id]
optional , nil allowed

External ID (manager only)

Validations:

  • Must be a String
user[role]
optional , nil allowed

Role (manager only)

Validations:

  • Must be a String
>>>

POST /api/users/one_time_user
Create a One-time User (manager only)

Creates (or updates) a user account that can only create one Inspection. Returns a URL that, when opened on the users device, will download and launch the Record360 application, with a default reference number (if specified). Users can be invited via email or phone number. If phone number is present and notify_user is true, a text message will be sent instead of an email.

Errors

Code Description
402 Sending messages by SMS is a paid feature. Your account does not have this feature enabled.
429 This API is rate limited. If you exceed the allowed limits the request will not be processed.

Examples

$ curl -i \
  -H "Accept: application/json; version=1" \
  -X POST \
  -H 'Content-type: application/json' \
  -H "Authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjQyLCJpYXQiOjE0NjM2OTQ4MjN9.k48v-R-un93KdIXqp9Zi12JOGJCu8uibtrWjscFCTqc" \
  -d '{"user": { "email": "[email protected]", "phone_number": "+12345678900", location_id": "1000001447", "external_id": "J. Random", "transaction_limit": 1 }, "reference_number": "12345", "notify_user": true}' \
  https://api.record360.com/api/users/one_time_user

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate

{
  "user": {
    "id": "42",
    "username": "[email protected]",
    "email": "[email protected]"
    "phone_number": "+12345678900",
    "transaction_limit": 1
  },
  "url":"https://launch.record360.com/tMoS/29QIKDx6lK"
}

Notes:
Notification by phone number is a paid feature.
Phone number will only be returned if it is sent in the request.

Params

Param name Description
user
required

User attributes

Validations:

  • Must be a Hash
user[email]
required

Username or email address, must be globally unique

Validations:

  • Must be a String
user[phone_number]
optional

Phone number with country code to send SMS text message. Example: +12345678900

Validations:

  • Must be a String
user[location_id]
required

Location ID

Validations:

  • Must be a String
user[external_id]
optional

External ID (integrator-assigned user identifier)

Validations:

  • Must be a String
user[transaction_limit]
optional

Transaction Limit (5 max)

Validations:

  • Must be a Integer
reference_number
optional

Default Reference Number for this user’s next Inspection

Validations:

  • Must be a String
notify_user
optional

Notify new user via email or phone. Default to false.

Validations:

  • Must be one of: true, false, 1, 0.
>>>

PATCH /api/users/:id
Update a User (manager only for other users)

PUT /api/users/:id
Update a User (manager only for other users)

Examples

$ curl -i \
  -H "Accept: application/json; version=1" \
  -H "Authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjQyLCJpYXQiOjE0NjM2OTQ4MjN9.k48v-R-un93KdIXqp9Zi12JOGJCu8uibtrWjscFCTqc" \
  -X PUT \
  -H 'Content-type: application/json' \
  -d '{"user": { "last_name": "Smith" }}' \
  https://api.record360.com/api/user/42

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate

{
  "user": {
    "id": "42",
    "username": "[email protected]",
    "first_name": "John",
    "last_name": "Smith",
    "external_id": "j_beeblebrox42",
    "created_at": "2016-05-23T22:16:43.000Z",
    "updated_at": "2016-05-23T22:16:43.000Z",
  }
}

Params

Param name Description
id
required

User ID, _externalid, or “self”

Validations:

  • Must be a String
user
required

User attributes

Validations:

  • Must be a Hash
user[username]
optional

Username or email address, must be globally unique

Validations:

  • Must be a String
user[password]
optional

Password

Validations:

  • Must be a String
user[first_name]
optional

First name

Validations:

  • Must be a String
user[last_name]
optional

Last name

Validations:

  • Must be a String
user[phone_number]
optional

Phone number

Validations:

  • Must be a String
user[active]
optional , nil allowed

Account enabled? (manager only)

Validations:

  • Must be one of: true, false, 1, 0.
user[location_id]
optional

Location ID (manager only)

Validations:

  • Must be a String
user[external_id]
optional

External ID (manager only)

Validations:

  • Must be a String
user[role]
optional

Role (manager only)

Validations:

  • Must be a String
>>>

DELETE /api/users/:id
Delete a User (manager only)

Examples

$ curl -i \
  -H "Accept: application/json; version=1" \
  -H "Authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjQyLCJpYXQiOjE0NjM2OTQ4MjN9.k48v-R-un93KdIXqp9Zi12JOGJCu8uibtrWjscFCTqc" \
  -X DELETE \
  https://api.record360.com/api/users/42

HTTP/1.1 204 No Content

Params

Param name Description
id
required

User ID or _externalid

Validations:

  • Must be a String
>>>

POST /api/users/:id/reset_password
Reset User Password (manager only)

Examples

$ curl -i \
  -H "Accept: application/json; version=1" \
  -H "Authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjQyLCJpYXQiOjE0NjM2OTQ4MjN9.k48v-R-un93KdIXqp9Zi12JOGJCu8uibtrWjscFCTqc" \
  -X POST \
  -H 'Content-type: application/json' \
  https://api.record360.com/api/users/42/reset_password

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate

{
  "user":{
    "id":"42",
    "email":"[email protected]"
  },
  "reset_password_url":"https://www.record360.com/users/password/edit?reset_password_token=NXsKDx4MsTATxcpyWhCw"
}

Params

Param name Description
id
required

User id

Validations:

  • Must be a String