> ## Documentation Index > Fetch the complete documentation index at: https://docs.gridbeds.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a guest > Creates a guest in the organization, to be named as `guest_id` when creating a reservation. Requires the `guests.write` scope. Send an `Idempotency-Key` header to make a retry safe: for at least 24 hours, the same key with the same body answers with the first response instead of creating a second guest. ## OpenAPI ````yaml /openapi/integration-v1.json post /v1/integration/guests openapi: 3.1.2 info: title: Gridbeds Integration API version: 2.0.0 description: >- The Gridbeds public integration API. Authenticate with a scoped Bearer token issued to your installed app; every request is isolated to that app's organization. termsOfService: https://gridbeds.com/en/terms/ contact: name: Gridbeds support email: support@gridbeds.com license: name: Proprietary url: https://gridbeds.com/en/terms/ servers: - url: https://api.gridbeds.com/api description: Production - url: https://staging-api.gridbeds.com/api description: Sandbox security: - bearerAuth: [] tags: - name: Identity description: >- Who the token belongs to: the installation, its organization and the scopes it was granted. - name: Reservations description: The organization's reservations. - name: Guests description: The organization's guest profiles, which a reservation is made for. paths: /v1/integration/guests: post: tags: - Guests summary: Create a guest description: >- Creates a guest in the organization, to be named as `guest_id` when creating a reservation. Requires the `guests.write` scope. Send an `Idempotency-Key` header to make a retry safe: for at least 24 hours, the same key with the same body answers with the first response instead of creating a second guest. operationId: createGuest parameters: - name: Idempotency-Key in: header description: >- A key of your choosing, such as a UUID, that makes a retry safe: for at least 24 hours the same key with the same body answers with the first response instead of repeating the write. Only a successful response is remembered; after a failure the same key may be tried again. schema: type: string maxLength: 255 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StoreIntegrationGuestRequest' responses: '201': description: The guest created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Guest' meta: type: object properties: message: type: string const: Guest created. required: - message required: - data - meta '401': description: >- Unauthenticated: the token is missing, unknown or revoked. A user's own sign-in token is refused the same way. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Forbidden. The token was not granted the `guests.write` scope, or its installation is disabled or in error. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The first request with this `Idempotency-Key` is still being processed (`code`: `idempotency_in_flight`). Retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- The request failed validation (`errors` names each field), or it asks for something the organization cannot do (`code` says what). A repeated `Idempotency-Key` sent with a different body is refused too (`code`: `idempotency_key_reused`). content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Too many requests: an installation may make 120 per minute. Wait `Retry-After` seconds. content: application/json: schema: $ref: '#/components/schemas/RateLimitError' headers: Retry-After: description: Seconds until the next request is counted afresh. schema: type: integer X-RateLimit-Limit: description: Requests allowed in the window. schema: type: integer X-RateLimit-Remaining: description: 'Requests left in the window: 0 here.' schema: type: integer X-RateLimit-Reset: description: When the window ends, as a Unix timestamp. schema: type: integer components: schemas: StoreIntegrationGuestRequest: type: object description: A guest to create. properties: first_name: type: string description: The guest's first name. maxLength: 255 last_name: type: string description: The guest's last name. maxLength: 255 email: type: - string - 'null' format: email description: The guest's email address. maxLength: 255 phone: type: - string - 'null' description: The guest's phone number. maxLength: 20 address: type: - string - 'null' description: The street address. maxLength: 255 city: type: - string - 'null' description: The city. maxLength: 100 country: type: - string - 'null' description: The guest's country, as a two-letter ISO 3166-1 alpha-2 code. minLength: 2 maxLength: 2 language: type: string description: >- The language the guest prefers to be written to in, as a language code such as `en`. Omit it for the default. postal_code: type: - string - 'null' description: The postal code. maxLength: 20 codice_fiscale: type: - string - 'null' description: >- The guest's Italian tax code (codice fiscale), for guests it applies to. Letters are upper-cased and spaces removed before it is checked. document_type: type: - string - 'null' description: The kind of identity document the guest travels on. enum: - passport - id_card - driving_license - null document_number: type: - string - 'null' description: The number of that document. maxLength: 50 date_of_birth: type: - string - 'null' format: date description: The guest's date of birth, as `YYYY-MM-DD`. Before today. nationality: type: - string - 'null' description: The guest's nationality, as a two-letter ISO 3166-1 alpha-2 code. minLength: 2 maxLength: 2 is_vip: type: boolean description: Whether the guest is marked as a VIP. Defaults to false. is_blacklisted: type: boolean description: Whether the guest is blacklisted. Defaults to false. required: - first_name - last_name title: StoreIntegrationGuestRequest Guest: type: object properties: id: type: string format: uuid description: The guest's id. organization_id: type: string format: uuid description: >- The organization the record belongs to: always the one that installed the app. first_name: type: string description: The guest's first name. last_name: type: string description: The guest's last name. email: type: - string - 'null' description: The guest's email address, when one is known. phone: type: - string - 'null' description: The guest's phone number, when one is known. required: - id - organization_id - first_name - last_name - email - phone title: Guest Error: type: object description: The body of a refused request. properties: message: type: string description: >- What went wrong, in a sentence for a person. Do not match on it: the wording can change and follows the request's language. code: type: string description: >- A stable identifier of the refusal, present when it has one, such as `idempotency_key_reused`. Match on this. errors: type: object description: >- Present on a validation failure: the messages for each field that failed, keyed by field name. additionalProperties: type: array items: type: string required: - message title: Error RateLimitError: type: object description: The body of a request refused for exceeding the installation's quota. properties: error: type: string description: Always `Too Many Requests`. message: type: string description: What happened, in a sentence for a person. retry_after: type: integer description: Seconds to wait before the next request. required: - error - message - retry_after title: RateLimitError securitySchemes: bearerAuth: type: http description: >- An integration token, sent as `Authorization: Bearer `. A token belongs to one installation of an app. Someone at the property who may manage its integrations installs the app in Gridbeds, under Settings → Integrations, and issues the token there, granting the scopes the app requested or a subset of them. The token is shown once; issuing a new one revokes the previous one. Every request reads and writes the data of the organization that installed the app, and nothing else. Each operation names the scope it requires. A token without that scope, and the token of an installation that is disabled or in error, are refused with 403; a token that is missing, unknown or revoked, and a user's own sign-in token, are refused with 401. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.