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
>>>

POST /api/users/multipart_upload_start/:file_id
Start a multipart upload

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

  1. Call this endpoint with a unique file_id (UUID) to identify the final file and the number of parts (part_count).
  2. The response includes an upload_id and presigned URLs for all parts.
  3. Upload each part to its corresponding presigned URL using a standard HTTP PUT request.
  4. After all parts are uploaded, call the complete endpoint with the upload_id and part ETags.
  5. Reference the uploaded file by file_id in other API endpoints.

Behavior

  • The file_id is a business-level identifier that will be used to reference the file in other parts of the system.
  • The upload_id is an AWS S3-specific identifier for tracking the multipart upload session.
  • part_count must be specified upfront and cannot be changed later.
  • Presigned URLs are provided for all parts specified in part_count.
  • Parts can be uploaded in any order - the part number is used to reconstruct the file in the correct order.
  • Parts can be uploaded in parallel for better performance.
  • Each part must be at least 5MB in size (except the last part).
  • Maximum part size is 5GB (5,120MB).
  • Maximum number of parts is 20 (Record360 Imposed Limit).
  • The complete endpoint must be called with all parts’ ETags to finalize the upload.
  • If an upload fails, you can retry with the same file_id and upload_id.
  • Presigned URLs expire after 24 hours. The complete endpoint must be called before all URLs expire.

Examples

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "new_file_42",
  "upload_id": "example-upload-id",
  "key": "users/42/new_file_42",
  "presigned_urls": [
    "https://bucket.s3.amazonaws.com/users/42/new_file_42?partNumber=1&uploadId=example-upload-id&...",
    "https://bucket.s3.amazonaws.com/users/42/new_file_42?partNumber=2&uploadId=example-upload-id&...",
    "https://bucket.s3.amazonaws.com/users/42/new_file_42?partNumber=3&uploadId=example-upload-id&..."
  ]
}

Params

Param name Description
file_id
required

UUID that will identify the final uploaded file. This is a business-level identifier that will be used to reference the file in other parts of the system.

Validations:

  • Must be a String
part_count
required

Number of parts the file will be split into. Must be between 1 and 20.

Validations:

  • Must be one of: String, Integer.
>>>

POST /api/users/multipart_upload_complete/:file_id
Complete a multipart upload

Examples

$ curl -i \
  -H 'Accept: application/json; version=1' \
  -H "Authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjQyLCJpYXQiOjE0NjM2OTQ4MjN9.k48v-R-un93KdIXqp9Zi12JOGJCu8uibtrWjscFCTqc" \
  -X POST \
  -H 'Content-type: application/json' \
  -d '{"upload_id": "example-upload-id", "parts": [{"part_number": 1, "etag": "etag1"}, {"part_number": 2, "etag": "etag2"}]}' \
  https://api.record360.com/api/users/multipart_upload_complete/new_file_42

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "new_file_42",
  "location": "https://bucket.s3.amazonaws.com/users/42/new_file_42",
  "etag": "final-etag",
  "filesize": 1048576,
  "checksum": "abc123def456"
}

Params

Param name Description
file_id
required

UUID that identifies the final uploaded file. Must match the file_id used in multipart_upload_start.

Validations:

  • Must be a String
upload_id
required

AWS S3-generated identifier for tracking the multipart upload session. This is separate from the file_id to allow retrying failed uploads.

Validations:

  • Must be a String
parts
required

Array of uploaded parts with ETags

Validations:

  • Must be an Array of nested elements
parts[part_number]
required

Part number (1-based)

Validations:

  • Must be a Integer
parts[etag]
required

ETag of the uploaded part

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 one of: String, 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