Users

The User resource

All users that have purchased a phone plan and have a subscription currently or in the past.

Properties

Name
object
Type
string
Description
Type of object is always user.
Name
id
Type
string
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
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
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
Name
createdAt
Type
string
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z

Response

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

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

Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
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
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
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z

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",
  "email": "jerry@example.com",
  "emailVerified": true,
  "fullName": "Jerry Seinfeld",
  "preferredLocale": "en-US",
  "createdAt": "2021-01-21T19:38:34Z"
}

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

Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
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
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
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z

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",
  "email": "jerry@example.com",
  "emailVerified": true,
  "fullName": "Jerry Seinfeld",
  "preferredLocale": "en-US",
  "createdAt": "2021-01-21T19:38:34Z"
}

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

Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
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
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
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z

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",
  "email": "jerry@example.com",
  "emailVerified": true,
  "fullName": "Jerry Seinfeld",
  "preferredLocale": "en-US",
  "createdAt": "2021-01-21T19:38:34Z"
}

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

Name
object
Type
string
required
Description
Type of object is always 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",
      "email": "jerry@example.com",
      "emailVerified": true,
      "fullName": "Jerry Seinfeld",
      "preferredLocale": "en-US",
      "createdAt": "2021-01-21T19:38:34Z"
    }
  ],
  "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

Name
object
Type
string
required
Description
Type of object is always 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",
      "email": "jerry@example.com",
      "emailVerified": true,
      "fullName": "Jerry Seinfeld",
      "preferredLocale": "en-US",
      "createdAt": "2021-01-21T19:38:34Z"
    }
  ],
  "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
object
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

Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
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
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
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z

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",
  "email": "jerry@example.com",
  "emailVerified": true,
  "fullName": "Jerry Seinfeld",
  "preferredLocale": "en-US",
  "createdAt": "2021-01-21T19:38:34Z"
}