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

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

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

  • 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",
      "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

  • 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",
      "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
    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
    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"
}