Users

The User resource

Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions.

Properties

Name
object
Type
string
Description
Type of object is always user.
Allowed values: user
Name
id
Type
string
Description
Unique identifier for the user.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
Name
metadata
Type
Metadata
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
Description
The birthday of the user.
Example: "2017-07-21"
Name
createdAt
Type
string
Description
Time when the user was created.
Example: "2021-01-21T19:38:34Z"
Name
email
Type
string
Description
The primary email address of the user.
Example: "jerry@example.com"
Name
emailVerified
Type
boolean
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
Description
The user's full name. Required for some Plans.
Example: "Jerry Seinfeld"
Name
preferredLocale
Type
string
Description
The user's locale preference represented as an IETF language tag.
Example: "en-US"

Response

{
  "object": "user",
  "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
  "birthday": "2017-07-21",
  "createdAt": "2021-01-21T19:38:34Z",
  "email": "jerry@example.com",
  "emailVerified": true,
  "fullName": "Jerry Seinfeld",
  "preferredLocale": "en-US"
}

GET/projects/{project}/users/{user}

Retrieve a user

Retrieves the details of an existing user. You need only supply the unique user identifier that was returned upon user creation.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
user
Type
string
required
Description
The unique identifier for the user.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Response Schemas

Returns the user object if the user exists.

Name
object
Type
string
required
Description
Type of object is always user.
Allowed values: user
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: "2017-07-21"
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: "2021-01-21T19:38:34Z"
Name
email
Type
string
required
Description
The primary email address of the user.
Example: "jerry@example.com"
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: "Jerry Seinfeld"
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: "en-US"

Request

GET

/projects/{project}/users/{user}

curl https://api.gigs.com/projects/{project}/users/{user} \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "user",
  "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
  "metadata": {},
  "birthday": "2017-07-21",
  "createdAt": "2021-01-21T19:38:34Z",
  "email": "jerry@example.com",
  "emailVerified": true,
  "fullName": "Jerry Seinfeld",
  "preferredLocale": "en-US"
}

DELETE/projects/{project}/users/{user}

Delete a user

Retrieves the details of an existing user and deletes it.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
user
Type
string
required
Description
The unique identifier for the user.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Response Schemas

Returns the user after a successful deletion.

Name
object
Type
string
required
Description
Type of object is always user.
Allowed values: user
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: "2017-07-21"
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: "2021-01-21T19:38:34Z"
Name
email
Type
string
required
Description
The primary email address of the user.
Example: "jerry@example.com"
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: "Jerry Seinfeld"
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: "en-US"

Request

DELETE

/projects/{project}/users/{user}

curl https://api.gigs.com/projects/{project}/users/{user} \
-X DELETE \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "user",
  "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
  "metadata": {},
  "birthday": "2017-07-21",
  "createdAt": "2021-01-21T19:38:34Z",
  "email": "jerry@example.com",
  "emailVerified": true,
  "fullName": "Jerry Seinfeld",
  "preferredLocale": "en-US"
}

PATCH/projects/{project}/users/{user}

Update a user

Updates the specified user by setting the values of the parameters passed.

Body

Name
birthday
Type
nullable string
Description
The birthday of the user.
Example: "2017-07-21"
Name
email
Type
nullable string
Description
The primary verified email address of the user.
Example: "jerry@example.com"
Name
fullName
Type
nullable string
Description
The user's full name. Required for some Plans.
Example: "Jerry Seinfeld"
Name
metadata
Type
Metadata
Description
A set of key-value pairs, to store metadata related to the resource.
Name
preferredLocale
Type
nullable string
Description
The user's locale preference represented as an IETF language tag.
Example: "en-US"

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
user
Type
string
required
Description
The unique identifier for the user.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Response Schemas

Returns the updated user.

Name
object
Type
string
required
Description
Type of object is always user.
Allowed values: user
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: "2017-07-21"
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: "2021-01-21T19:38:34Z"
Name
email
Type
string
required
Description
The primary email address of the user.
Example: "jerry@example.com"
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: "Jerry Seinfeld"
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: "en-US"

Request

PATCH

/projects/{project}/users/{user}

curl https://api.gigs.com/projects/{project}/users/{user} \
-X PATCH \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"birthday\":\"2017-07-21\",\"email\":\"jerry@example.com\",\"fullName\":\"Jerry Seinfeld\",\"metadata\":{},\"preferredLocale\":\"en-US\"}"

Response

{
  "object": "user",
  "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
  "metadata": {},
  "birthday": "2017-07-21",
  "createdAt": "2021-01-21T19:38:34Z",
  "email": "jerry@example.com",
  "emailVerified": true,
  "fullName": "Jerry Seinfeld",
  "preferredLocale": "en-US"
}

POST/projects/{project}/users/search

Search for users

Searches for existing users matching the given parameters.

Body

Name
email
Type
nullable string
Description
The primary email address of the user.
Example: "jerry@example.com"

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Response Schemas

Returns the users matching the search criteria.

Name
object
Type
string
required
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
required
Description
List of objects of type `user`.
Name
moreItemsAfter
Type
nullable string
required
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
required
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

POST

/projects/{project}/users/search

curl https://api.gigs.com/projects/{project}/users/search \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"email\":\"jerry@example.com\"}"

Response

{
  "object": "list",
  "items": [
    {
      "object": "user",
      "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
      "metadata": {},
      "birthday": "2017-07-21",
      "createdAt": "2021-01-21T19:38:34Z",
      "email": "jerry@example.com",
      "emailVerified": true,
      "fullName": "Jerry Seinfeld",
      "preferredLocale": "en-US"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

GET/projects/{project}/users

List all users

Returns a list of users. The users returned are sorted by creation date, with the most recently created users appearing first.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Query Parameters

Name
after
Type
string
Description
A cursor for use in pagination. The after parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned.
Name
before
Type
string
Description
A cursor for use in pagination. The before parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned.
Name
limit
Type
integer
Description
The limit of items to be returned in the list, between 0 and 200.
Default: 10
>= 0
<= 200

Response Schemas

Returns a dictionary with an items property that contains an array of user objects.

Name
object
Type
string
required
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
required
Description
List of objects of type `user`.
Name
moreItemsAfter
Type
nullable string
required
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
required
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/projects/{project}/users

curl https://api.gigs.com/projects/{project}/users \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "list",
  "items": [
    {
      "object": "user",
      "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
      "metadata": {},
      "birthday": "2017-07-21",
      "createdAt": "2021-01-21T19:38:34Z",
      "email": "jerry@example.com",
      "emailVerified": true,
      "fullName": "Jerry Seinfeld",
      "preferredLocale": "en-US"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

POST/projects/{project}/users

Create a user

Creates a new user with the given parameters.

Body

Name
birthday
Type
nullable string
Description
The birthday of the user.
Example: "2017-07-21"
Name
email
Type
string
required
Description
The primary verified email address of the user.
Example: "jerry@example.com"
Name
fullName
Type
nullable string
Description
The user's full name. Some plans require the user name to be present when creating a subscription. Check the plan requirements for that.
Example: "Jerry Seinfeld"
Name
metadata
Type
Metadata
Description
A set of key-value pairs, to store metadata related to the resource.
Name
preferredLocale
Type
nullable string
Description
The user's locale preference represented as an IETF language tag. It defaults to the project's preferred locale.
Example: "en-US"

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Response Schemas

Returns the created user.

Name
object
Type
string
required
Description
Type of object is always user.
Allowed values: user
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: "2017-07-21"
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: "2021-01-21T19:38:34Z"
Name
email
Type
string
required
Description
The primary email address of the user.
Example: "jerry@example.com"
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: "Jerry Seinfeld"
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: "en-US"

Request

POST

/projects/{project}/users

curl https://api.gigs.com/projects/{project}/users \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"birthday\":\"2017-07-21\",\"email\":\"jerry@example.com\",\"fullName\":\"Jerry Seinfeld\",\"metadata\":{},\"preferredLocale\":\"en-US\"}"

Response

{
  "object": "user",
  "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
  "metadata": {},
  "birthday": "2017-07-21",
  "createdAt": "2021-01-21T19:38:34Z",
  "email": "jerry@example.com",
  "emailVerified": true,
  "fullName": "Jerry Seinfeld",
  "preferredLocale": "en-US"
}