> ## Documentation Index > Fetch the complete documentation index at: https://docs.lobbystack.com/llms.txt > Use this file to discover all available pages before exploring further. # Generate keypad PINs > Gives contacts a random keypad PIN and returns each one in new_passcode. LobbyStack keeps only a hash, so this response is the only time the PINs appear: give each contact theirs. With contact_ids, those contacts get a new PIN, replacing any they have. Without it, contacts that have a phone number and no PIN get one, oldest first, 20 per request: send it again until remaining is 0. This endpoint ignores Idempotency-Key, so no copy of a PIN is stored. After a network error, look for contacts whose passcode set_at is from that request, and give them new PINs with contact_ids. As in the dashboard, only owners and admins set PINs: a per-business key whose creator no longer is one gets a 403 key_owner_inactive. ## OpenAPI ````yaml /api-reference/openapi.json post /contacts/passcodes/generate openapi: 3.1.0 info: title: LobbyStack API version: v1 description: >- Read calls, contacts, appointments and messages, book appointments, and subscribe to webhooks. Authenticate with an API key in the Authorization header. A platform key also names the business it acts on in the LobbyStack-Business header. Each key allows 120 requests per minute by default. servers: - url: https://app.lobbystack.com/api/v1 security: - bearerAuth: [] tags: - name: Business - name: Receptionist - name: Billing - name: Phone numbers - name: Onboarding - name: Team - name: Website chat - name: Calendars - name: Notifications - name: Calls - name: Contacts - name: Appointments - name: Messages - name: Knowledge - name: Webhooks - name: Platform paths: /contacts/passcodes/generate: post: tags: - Contacts summary: Generate keypad PINs description: >- Gives contacts a random keypad PIN and returns each one in new_passcode. LobbyStack keeps only a hash, so this response is the only time the PINs appear: give each contact theirs. With contact_ids, those contacts get a new PIN, replacing any they have. Without it, contacts that have a phone number and no PIN get one, oldest first, 20 per request: send it again until remaining is 0. This endpoint ignores Idempotency-Key, so no copy of a PIN is stored. After a network error, look for contacts whose passcode set_at is from that request, and give them new PINs with contact_ids. As in the dashboard, only owners and admins set PINs: a per-business key whose creator no longer is one gets a 403 key_owner_inactive. operationId: generateContactPasscodes parameters: - name: LobbyStack-Business in: header description: >- The business a platform key acts on. Required with a platform key. A per-business key may leave it out; if it sends one, it must be the key's own business. schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ContactPasscodesGenerate' responses: '200': description: OK content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/GeneratedContactPasscodes' '400': description: >- The request is invalid (invalid_request), or a platform key sent no LobbyStack-Business header (business_required). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: The API key is missing, invalid, or revoked (unauthorized). content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Refused. insufficient_scope: the key lacks the contacts:write scope. forbidden: a per-business key named another business in LobbyStack-Business. key_owner_inactive: the person the key acts for can't any more: a per-business key's creator is no longer an owner or admin, or a platform key's owner_email has no verified LobbyStack account. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: A platform key named a business it cannot act on (not_found). content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The request conflicts with the current state. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Too many requests (rate_limited). Wait for the Retry-After header's number of seconds. content: application/json: schema: $ref: '#/components/schemas/Error' headers: Retry-After: schema: type: integer description: Seconds to wait. security: - bearerAuth: [] components: schemas: ContactPasscodesGenerate: type: object properties: contact_ids: description: >- 1 to 20 contacts to give a new PIN, each once, replacing any PIN they have. Leave it out to give one to contacts that have a phone number and no PIN. minItems: 1 maxItems: 20 type: array items: type: string format: uuid description: Stable identifier (UUID). length: description: Digits in each PIN, 4 to 8. Defaults to 6. type: integer minimum: 4 maximum: 8 additionalProperties: false GeneratedContactPasscodes: type: object properties: contacts: type: array items: type: object properties: id: type: string format: uuid description: Stable identifier (UUID). name: type: - string - 'null' phone: type: - string - 'null' email: type: - string - 'null' locale: type: - string - 'null' timezone: type: - string - 'null' passcode: anyOf: - type: object properties: set_at: type: string format: date-time description: ISO 8601 timestamp in UTC. locked: type: boolean description: >- true after 5 wrong PINs in a row, even across calls. A locked PIN works again only once a new one is set. required: - set_at - locked additionalProperties: false - type: 'null' description: >- The contact's keypad PIN, which callers type to change appointments when verification_mode is passcode_required: whether there is one, never the PIN itself. null: the contact has no PIN. created_at: type: string format: date-time description: ISO 8601 timestamp in UTC. updated_at: type: string format: date-time description: ISO 8601 timestamp in UTC. new_passcode: type: string description: >- The PIN just set. LobbyStack keeps only a hash of it, so this is the only time it's shown: give it to the contact. required: - id - name - phone - email - locale - timezone - passcode - created_at - updated_at - new_passcode additionalProperties: false description: The contacts that got a new PIN. remaining: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Contacts that have a phone number and still no PIN. Without contact_ids, send the request again until this is 0. required: - contacts - remaining additionalProperties: false Error: type: object properties: error: type: object properties: code: type: string enum: - invalid_request - unauthorized - forbidden - insufficient_scope - not_found - conflict - idempotency_key_reused - idempotency_request_in_progress - booking_disabled - booking_requires_confirmation - slot_unavailable - rate_limited - rate_limit_unavailable - method_not_allowed - internal_error - business_required - key_owner_inactive - plan_limit_reached message: type: string details: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: false required: - code - message additionalProperties: false required: - error additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key from Settings > API keys (lsk_...), which acts on its own business, or a platform key from the PLATFORM_API_KEYS setting (lsp_...), which onboards and manages businesses. Scopes: business:read, business:write, calls:read, contacts:read, contacts:write, appointments:read, appointments:write, messages:read, knowledge:read, knowledge:write, webhooks:manage, billing:manage, phone_numbers:manage, team:manage, businesses:create, users:create. Only platform keys can hold businesses:create and users:create. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.