# Users ## The User object Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `user`. | | `id` | string | Yes | Unique identifier for the user. | | `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `birthday` | string,null | Yes | The birthday of the user. | | `createdAt` | string | Yes | Time when the user was created. | | `email` | string | Yes | The primary email address of the user. Must be unique across all users. | | `emailVerified` | boolean | Yes | Whether the user's primary email address is verified or not. | | `fullName` | string,null | Yes | The user's full name. Required for some Plans. | | `preferredLocale` | string | Yes | The user's locale preference represented as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag). | | `status` | active | blocked | deleted | Yes | The current status of the user. | --- ## List all users `GET /projects/{project}/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 | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `after` | string | No | 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. | | `before` | string | No | 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. | | `limit` | integer | No | The limit of items to be returned in the list, between 0 and 200. | ### Responses #### 200 — Returns a dictionary with an items property that contains an array of user objects. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `list`. | | `items` | object[] | Yes | List of objects of type `user`. | | `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. | | `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. | --- ## Create a user `POST /projects/{project}/users` Creates a new user with the given parameters. ### Body | Property | Type | Required | Description | |----------|------|----------|-------------| | `birthday` | string,null | No | The birthday of the user. | | `email` | string | Yes | The primary verified email address of the user. | | `fullName` | string,null | No | The user's full name. Some plans require the user name to be present when creating a subscription. Check the plan requirements for that. | | `metadata` | object | No | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `preferredLocale` | string,null | No | The user's locale preference represented as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag). It defaults to the project's preferred locale. | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | ### Responses #### 201 — Returns the created user. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `user`. | | `id` | string | Yes | Unique identifier for the user. | | `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `birthday` | string,null | Yes | The birthday of the user. | | `createdAt` | string | Yes | Time when the user was created. | | `email` | string | Yes | The primary email address of the user. Must be unique across all users. | | `emailVerified` | boolean | Yes | Whether the user's primary email address is verified or not. | | `fullName` | string,null | Yes | The user's full name. Required for some Plans. | | `preferredLocale` | string | Yes | The user's locale preference represented as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag). | | `status` | active | blocked | deleted | Yes | The current status of the user. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Retrieve a user `GET /projects/{project}/users/{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 | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `user` | string | Yes | The unique identifier for the user. | ### Responses #### 200 — Returns the user object if the user exists. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `user`. | | `id` | string | Yes | Unique identifier for the user. | | `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `birthday` | string,null | Yes | The birthday of the user. | | `createdAt` | string | Yes | Time when the user was created. | | `email` | string | Yes | The primary email address of the user. Must be unique across all users. | | `emailVerified` | boolean | Yes | Whether the user's primary email address is verified or not. | | `fullName` | string,null | Yes | The user's full name. Required for some Plans. | | `preferredLocale` | string | Yes | The user's locale preference represented as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag). | | `status` | active | blocked | deleted | Yes | The current status of the user. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Delete a user `DELETE /projects/{project}/users/{user}` Retrieves the details of an existing user and deletes it. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `user` | string | Yes | The unique identifier for the user. | ### Responses #### 200 — Returns the user after a successful deletion. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `user`. | | `id` | string | Yes | Unique identifier for the user. | | `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `birthday` | string,null | Yes | The birthday of the user. | | `createdAt` | string | Yes | Time when the user was created. | | `email` | string | Yes | The primary email address of the user. Must be unique across all users. | | `emailVerified` | boolean | Yes | Whether the user's primary email address is verified or not. | | `fullName` | string,null | Yes | The user's full name. Required for some Plans. | | `preferredLocale` | string | Yes | The user's locale preference represented as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag). | | `status` | active | blocked | deleted | Yes | The current status of the user. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Update a user `PATCH /projects/{project}/users/{user}` Updates the specified user by setting the values of the parameters passed. ### Body | Property | Type | Required | Description | |----------|------|----------|-------------| | `birthday` | string,null | No | The birthday of the user. | | `email` | string,null | No | The primary verified email address of the user. | | `fullName` | string,null | No | The user's full name. Required for some Plans. | | `metadata` | object | No | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `preferredLocale` | string,null | No | The user's locale preference represented as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag). | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `user` | string | Yes | The unique identifier for the user. | ### Responses #### 200 — Returns the updated user. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `user`. | | `id` | string | Yes | Unique identifier for the user. | | `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `birthday` | string,null | Yes | The birthday of the user. | | `createdAt` | string | Yes | Time when the user was created. | | `email` | string | Yes | The primary email address of the user. Must be unique across all users. | | `emailVerified` | boolean | Yes | Whether the user's primary email address is verified or not. | | `fullName` | string,null | Yes | The user's full name. Required for some Plans. | | `preferredLocale` | string | Yes | The user's locale preference represented as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag). | | `status` | active | blocked | deleted | Yes | The current status of the user. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Search for users `POST /projects/{project}/users/search` Searches for existing users matching the given parameters. ### Body | Property | Type | Required | Description | |----------|------|----------|-------------| | `email` | string,null | No | The primary email address of the user. | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | ### Responses #### 200 — Returns the users matching the search criteria. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `list`. | | `items` | object[] | Yes | List of objects of type `user`. | | `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. | | `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | ---