We use cookies to give you the best possible experience while you browse through our site. By continuing to use our website you implicitly agree to the usage of cookies on this site.

Read More
← Atlas API & Provisioning Reference

Users

Schema

A user is any agent that can interact with impersonated or portal APIs

Type Object

Name Type Description
address address Desc. address
email String(format:email) Desc. email
first_name String Desc. first_name
id String(format:uuid) Desc. id
inserted_at String(format:date-time) An ISO8601 formatted timestamp
last_name String Desc. last_name
title String Desc. title
updated_at String(format:date-time) An ISO8601 formatted timestamp

Desc. address

User Address details, may differ from top-level details

Desc. email

User's email

Desc. first_name

User's first name

Desc. id

A Universally unique identifier, which identifies the resource

Desc. last_name

User's last name

Desc. title

User's job title, or position

address

Name Type Description
address1 String
address2 String
business_name String
city String
country String
email String
fax_number String
first_name String
house_number String
last_name String
notes String
phone_number String
state String
zip_code String

Example

{
  "address": {
    "address1": "string",
    "address2": "string",
    "business_name": "string",
    "city": "string",
    "country": "string",
    "email": "string",
    "fax_number": "string",
    "first_name": "string",
    "house_number": "string",
    "last_name": "string",
    "notes": "string",
    "phone_number": "string",
    "state": "string",
    "zip_code": "string"
  },
  "email": "[email protected]",
  "first_name": "John",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "last_name": "Doe",
  "title": "Operator",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Summary

Users are agents or actual human beings who are capable of utilizing the portal or API (via an Impersonated API Key).

Users are assigned a role which affect their permissions and access levels.

API

Create User

Data

Name Type Description
address address Desc. address
email String(format:email) Desc. email
first_name String Desc. first_name
last_name String Desc. last_name
password String Desc. password
password_confirmation String Desc. password_confirmation
title String Desc. title

Desc. address

User Address details, may differ from top-level details

Desc. email

User's email

Desc. first_name

User's first name

Desc. last_name

User's last name

Desc. password

User's login password

Desc. password_confirmation

User's login password (for confirmation)

Desc. title

User's job title, or position

address

Name Type Description
address1 String
address2 String
business_name String
city String
country String
email String
fax_number String
first_name String
house_number String
last_name String
notes String
phone_number String
state String
zip_code String 
POST /api/v1/users HTTP/1.1

Create a new User, they will be automatically assigned to the same role as current user.

Request application/json

POST /api/v1/users HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 632

{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "password": "string",
    "password_confirmation": "string",
    "title": "Operator"
  },
  "type": "user"
}

Response 201

application/json
HTTP/1.1 201
Content-Type: application/json
Content-Length: 716

{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "[email protected]",
    "first_name": "John",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "last_name": "Doe",
    "title": "Operator",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "user"
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 422

application/json
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241

{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Update User

Data

Name Type Description
address address Desc. address
email String(format:email) Desc. email
first_name String Desc. first_name
last_name String Desc. last_name
title String Desc. title

Desc. address

User Address details, may differ from top-level details

Desc. email

User's email

Desc. first_name

User's first name

Desc. last_name

User's last name

Desc. title

User's job title, or position

address

Name Type Description
address1 String
address2 String
business_name String
city String
country String
email String
fax_number String
first_name String
house_number String
last_name String
notes String
phone_number String
state String
zip_code String 
PATCH /api/v1/users/{id} HTTP/1.1

Update an existing User.

Path Parameters

Name Type Description
id String(format:uuid)! User ID

Request application/json

PATCH /api/v1/users/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 567

{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "title": "Operator"
  },
  "type": "user"
}

Response 200

application/json
HTTP/1.1 200
Content-Type: application/json
Content-Length: 716

{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "[email protected]",
    "first_name": "John",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "last_name": "Doe",
    "title": "Operator",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "user"
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Response 422

application/json
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241

{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Delete User

DELETE /api/v1/users/{id} HTTP/1.1

Delete an existing User by ID.

Path Parameters

Name Type Description
id String(format:uuid)! User ID

Request

DELETE /api/v1/users/{id} HTTP/1.1
Accept: application/json

Response 200

application/json
HTTP/1.1 200
Content-Type: application/json
Content-Length: 716

{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "[email protected]",
    "first_name": "John",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "last_name": "Doe",
    "title": "Operator",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "user"
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Response 422

application/json
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241

{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

List Users

GET /api/v1/users HTTP/1.1

Retrieve a list of users assigned to the parent account

Query Parameters

Name Type Description
first Integer Query Desc. first
last Integer Query Desc. last
after String Query Desc. after
before String Query Desc. before

Query Desc. first

The number of items to return starting from the 'after' cursor

Query Desc. last

The number of items to return behind the 'before' cursor

Query Desc. after

The cursor representing the starting point of a 'first' based paging

Query Desc. before

The cursor representing the starting point of a 'last' based paging

Request

GET /api/v1/users HTTP/1.1
Accept: application/json

Response 200

application/json
HTTP/1.1 200
Content-Type: application/json
Content-Length: 989

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "address": {
          "address1": "string",
          "address2": "string",
          "business_name": "string",
          "city": "string",
          "country": "string",
          "email": "string",
          "fax_number": "string",
          "first_name": "string",
          "house_number": "string",
          "last_name": "string",
          "notes": "string",
          "phone_number": "string",
          "state": "string",
          "zip_code": "string"
        },
        "email": "[email protected]",
        "first_name": "John",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "last_name": "Doe",
        "title": "Operator",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "user"
    }
  ]
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Get User

GET /api/v1/users/{id} HTTP/1.1

Lookup a user by ID

Path Parameters

Name Type Description
id String(format:uuid)! User ID

Request

GET /api/v1/users/{id} HTTP/1.1
Accept: application/json

Response 200

application/json
HTTP/1.1 200
Content-Type: application/json
Content-Length: 716

{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "[email protected]",
    "first_name": "John",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "last_name": "Doe",
    "title": "Operator",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "user"
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Updated 2026-08-12 · Generated from the Atlas OpenAPI spec.