> ## Documentation Index > Fetch the complete documentation index at: https://docs.snappy.com/llms.txt > Use this file to discover all available pages before exploring further. # Get recipients > Use this endpoint to retrieve a list of Recipients based on your specified criteria. Use this when building a recipient picker in your UI, syncing recipients to your system, or finding recipients by name, email, or external ID. ###### Filtering options: - `firstNames` query parameter - comma-separated list of first names - `lastNames` query parameter - comma-separated list of last names - `emails` query parameter - comma-separated list of email addresses (each must be a valid email format) - `emailOverrides` query parameter - comma-separated list of email override addresses - `externalIds` query parameter - comma-separated list of your-system IDs - `accountIds` query parameter - comma-separated list of Account IDs - `sources` query parameter - comma-separated list of recipient sources (`apiIntegration`, `hrisIntegration`, `manual`, `ftpIntegration`, `fileSync`) - `fields` query parameter - comma-separated field projection. Valid values: `id`, `createdAt`, `updatedAt`, `firstName`, `lastName`, `email`, `emailOverride`, `mobilePhone`, `country`, `externalId`, `accounts`, `updatedBy`, `source`, `owner`, `type`, `recipientCustomFields`, `birthday`, `full` - `companyId` query parameter - Company ID (when not inferable from the calling key) - `Request-Source` header - source of the request (`api_native`, `api_zapier`, `api_salesforce`, `api_ftp`, `api_make`) ###### Pagination: - `skip` query parameter - number of records to skip (default `0`) - `limit` query parameter - max records per page (1-200, default `200`) ###### Please note: - All array filters use OR semantics - passing multiple `firstNames` returns recipients matching any of the supplied names. - PII fields are masked unless your API key has the `recipients:read:unmasked` scope. #### Permissions - Requires: `recipients:read:masked` or `recipients:read:unmasked` ## OpenAPI ````yaml get /v2/recipients openapi: 3.0.0 info: title: Snappy Public API version: 2.0.0 contact: name: Snappy Support email: info@snappy.com description: >- Welcome to the Snappy API reference documentation! You can use this API to integrate with Snappy and spread smiles to your employees/clients/customers and much more. In just 3 simple steps you can start sending gifts today: pull the relevant campaign, send gifts to your recipients and track gift statuses. So let's get started! servers: - url: https://api.snappy.com/public-api description: Base API URL - url: https://mtls-api.snappy.com/public-api description: >- ## mTLS URL You can also use mTLS to enhance your API security. To get your specific certificates please contact our support. Once you configure the certificated correctly, you need to also update endpoints to use the following secure api base URL: security: [] tags: - name: Authentication description: >- API keys authenticate requests to the Snappy API. Use these endpoints to list active keys for your Company, create new keys, or delete keys you no longer need. - name: Accounts description: >- An **Account** is a sub-entity that lives within a **Company**. Accounts are used to separate and organize your company's campaigns and gift sends for different teams, departments or budget owners. - name: Campaigns description: >- A **Campaign** is the primary organizational object used to configure and send a batch of gifts. It acts as a template for all the settings of a single gifting initiative, including the target **Recipient** list, the selected **Collection** or **product**, the budget, branding, and notification messages. - name: Collections description: >- A **Collection** is a curated catalog of gift items tailored to a specific theme, budget range, and audience (e.g., "Birthday Gifts Under $50"). The gift recipient then chooses their preferred item directly from this collection. Use these endpoints to: - Get available collections based on budget and country requirements - Retrieve budget ranges for specific collections - Access collection details and products Please note: Swag collections can only be retrieved by specifying the accountId in the request. - name: Products & Variants description: >- Use these endpoints to search for and retrieve products and variants (including by collection and budget), and to list product tags for building catalog and filtering experiences in your UI. - name: Gifts description: >- A **Gift** is the core transactional object in the Snappy system. It represents the entire gifting experience for a **Recipient** within a **Campaign**, from initial creation to final delivery. The **Gift** object tracks the status and details through each stage of its lifecycle: 1. **Creation:** The gift is initiated and associated with a recipient and campaign. 2. **Notification:** The recipient is notified about their gift via email or other channels. 3. **Selection:** The recipient selects a specific product from the gift collection (if applicable). 4. **Order Generation:** An order is created based on the selected product and the recipient's shipping address. 5. **Delivery:** The physical product is shipped and its delivery status is tracked to completion. - name: Orders description: >- Endpoints for programmatically claiming gifts (ordering on behalf of recipients), cancelling orders before they ship, and validating or autocompleting shipping addresses as part of your checkout or fulfillment flow. - name: Recipients description: A **Recipient** is the end-user who receives a **Gift**. paths: /v2/recipients: get: tags: - Recipients summary: Get recipients description: >- Use this endpoint to retrieve a list of Recipients based on your specified criteria. Use this when building a recipient picker in your UI, syncing recipients to your system, or finding recipients by name, email, or external ID. ###### Filtering options: - `firstNames` query parameter - comma-separated list of first names - `lastNames` query parameter - comma-separated list of last names - `emails` query parameter - comma-separated list of email addresses (each must be a valid email format) - `emailOverrides` query parameter - comma-separated list of email override addresses - `externalIds` query parameter - comma-separated list of your-system IDs - `accountIds` query parameter - comma-separated list of Account IDs - `sources` query parameter - comma-separated list of recipient sources (`apiIntegration`, `hrisIntegration`, `manual`, `ftpIntegration`, `fileSync`) - `fields` query parameter - comma-separated field projection. Valid values: `id`, `createdAt`, `updatedAt`, `firstName`, `lastName`, `email`, `emailOverride`, `mobilePhone`, `country`, `externalId`, `accounts`, `updatedBy`, `source`, `owner`, `type`, `recipientCustomFields`, `birthday`, `full` - `companyId` query parameter - Company ID (when not inferable from the calling key) - `Request-Source` header - source of the request (`api_native`, `api_zapier`, `api_salesforce`, `api_ftp`, `api_make`) ###### Pagination: - `skip` query parameter - number of records to skip (default `0`) - `limit` query parameter - max records per page (1-200, default `200`) ###### Please note: - All array filters use OR semantics - passing multiple `firstNames` returns recipients matching any of the supplied names. - PII fields are masked unless your API key has the `recipients:read:unmasked` scope. #### Permissions - Requires: `recipients:read:masked` or `recipients:read:unmasked` operationId: getRecipients parameters: - schema: type: string pattern: ^[A-Za-z0-9]{8,}$ description: Company ID example: '12345678' required: false description: Company ID name: companyId in: query - schema: type: array items: type: string minItems: 1 uniqueItems: true description: The first name of the recipient. example: - John required: false description: The first name of the recipient. style: form explode: false name: firstNames in: query - schema: type: array items: type: string minItems: 1 uniqueItems: true description: The last name of the recipient. example: - Doe required: false description: The last name of the recipient. style: form explode: false name: lastNames in: query - schema: type: array items: type: string minItems: 1 uniqueItems: true description: The external id of the recipient. example: - '123' - '124' required: false description: The external id of the recipient. style: form explode: false name: externalIds in: query - schema: type: array items: type: string pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ minItems: 1 uniqueItems: true description: Recipient email addresses (must be valid email format). example: - sad@asd.com required: false description: Recipient email addresses (must be valid email format). style: form explode: false name: emails in: query - schema: type: array items: type: string pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ minItems: 1 uniqueItems: true description: >- Alternative email addresses to use for sending gifts, overriding the recipient's primary email. example: - sad@sad.com required: false description: >- Alternative email addresses to use for sending gifts, overriding the recipient's primary email. style: form explode: false name: emailOverrides in: query - schema: type: array items: type: string minItems: 1 uniqueItems: true description: The account id of the recipient. example: - a12bcd34 - a56bcd78 required: false description: The account id of the recipient. style: form explode: false name: accountIds in: query - schema: type: array items: $ref: '#/components/schemas/RecipientSource' minItems: 1 uniqueItems: true description: The source of the recipient. example: - apiIntegration - ftpIntegration required: false description: The source of the recipient. style: form explode: false name: sources in: query - schema: type: array items: $ref: '#/components/schemas/RecipientFields' minItems: 1 uniqueItems: true description: >- Fields to include in the response. Use 'full' to include all fields. example: - id - firstName required: false description: Fields to include in the response. Use 'full' to include all fields. style: form explode: false name: fields in: query - schema: $ref: '#/components/schemas/Skip' required: false description: >- Number of records to skip for pagination (use with limit for paging through results) name: skip in: query - schema: type: number minimum: 1 maximum: 200 default: 200 description: Maximum number of records to return per page example: 200 required: false description: Maximum number of records to return per page name: limit in: query - schema: $ref: '#/components/schemas/RequestSourceHeader' required: false description: Source of the request name: Request-Source in: header responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/GetRecipientsResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiStringError' '401': description: Unauthorized content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiStringError' - example: status: 401 errorCode: 401_PBLC_001 message: Unauthorized '403': description: Forbidden content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiStringError' - example: status: 403 errorCode: 403_PBLC_001 message: Forbidden '422': description: Unprocessable Entity content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiStringError' - example: status: 422 errorCode: 422_PBLC_001 message: Unprocessable Entity security: - CompanyLevelAuthentication: [] - BearerAuthentication: [] components: schemas: RecipientSource: type: string enum: - apiIntegration - hrisIntegration - manual - ftpIntegration - fileSync description: The source of the recipient. example: apiIntegration RecipientFields: type: string enum: - id - createdAt - updatedAt - firstName - lastName - email - emailOverride - mobilePhone - country - externalId - accounts - updatedBy - source - owner - type - recipientCustomFields - birthday - full description: Fields to include in the response. Use 'full' to include all fields. example: full Skip: type: number nullable: true minimum: 0 default: 0 description: >- Number of records to skip for pagination (use with limit for paging through results) example: 0 RequestSourceHeader: type: string enum: - api_native - api_zapier - api_salesforce - api_ftp - api_make description: Source of the request example: api_native GetRecipientsResponse: type: object properties: results: type: array items: allOf: - $ref: '#/components/schemas/Recipient' - description: Recipient object. example: id: xyz12345 createdAt: '2022-12-06T09:50:38.536Z' updatedAt: '2022-12-06T09:50:38.536Z' firstName: John lastName: Doe email: john.doe@example.com country: US accounts: - a12bcd34 - a56bcd78 type: employee updatedBy: abc12345 source: type: apiIntegration description: The results of the recipients query. skip: $ref: '#/components/schemas/Skip' limit: type: number nullable: true required: - results additionalProperties: false description: Response containing recipients. example: results: - id: xyz12345 createdAt: '2022-12-06T09:50:38.536Z' updatedAt: '2022-12-06T09:50:38.536Z' firstName: John lastName: Doe email: john.doe@example.com country: US accounts: - a12bcd34 - a56bcd78 type: employee updatedBy: abc12345 source: type: apiIntegration skip: 0 limit: 200 ApiStringError: type: object properties: status: type: integer description: The HTTP status code. example: 400 errorCode: type: string description: >- Internal error code, helps Snappy's technical team to troubleshoot if needed. example: 400_PBLC_001 message: type: string description: The error message. example: Unauthorized errors: type: array items: type: object properties: path: type: string description: The path of the field that caused the error. example: body.recipients.0.email message: type: string description: The error message. example: Invalid email. errorCode: type: string description: >- Internal error code, helps Snappy's technical team to troubleshoot if needed. example: 400_PBLC_002 required: - path - message - errorCode description: >- An array of client errors. This field is being returned only for errors the client should fix, usually with status code 400. required: - status - errorCode - message description: >- API error response with string error codes and optional client error details example: status: 400 errorCode: 400_PBLC_001 message: Bad Request Recipient: type: object properties: firstname: type: string pattern: >- ^(?=.{1,50}$)[a-zA-Z0-9_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u01FF\u0100-\u017F\u0180-\u024F\u1E00-\u1EFF\u0400-\u04FF\u0500-\u052F\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FFF\uAC00-\uD7AF\u0E00-\u0E7F][a-zA-Z0-9_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u01FF\u0100-\u017F\u0180-\u024F\u1E00-\u1EFF\u0400-\u04FF\u0500-\u052F\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FFF\uAC00-\uD7AF\u0E00-\u0E7F\u0300-\u036F\u1AB0-\u1AFF\u1DC0-\u1DFF\u20D0-\u20FF\uFE20-\uFE2F]*([\s\(\)\.\-_'\u2018\u2019]*[a-zA-Z0-9_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u01FF\u0100-\u017F\u0180-\u024F\u1E00-\u1EFF\u0400-\u04FF\u0500-\u052F\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FFF\uAC00-\uD7AF\u0E00-\u0E7F][a-zA-Z0-9_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u01FF\u0100-\u017F\u0180-\u024F\u1E00-\u1EFF\u0400-\u04FF\u0500-\u052F\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FFF\uAC00-\uD7AF\u0E00-\u0E7F\u0300-\u036F\u1AB0-\u1AFF\u1DC0-\u1DFF\u20D0-\u20FF\uFE20-\uFE2F]*)*[ \(\)\.\-_'\u2018\u2019]*$ description: The first name of the recipient. example: John lastname: type: string pattern: >- ^(?=.{1,50}$)[a-zA-Z0-9_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u01FF\u0100-\u017F\u0180-\u024F\u1E00-\u1EFF\u0400-\u04FF\u0500-\u052F\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FFF\uAC00-\uD7AF\u0E00-\u0E7F][a-zA-Z0-9_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u01FF\u0100-\u017F\u0180-\u024F\u1E00-\u1EFF\u0400-\u04FF\u0500-\u052F\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FFF\uAC00-\uD7AF\u0E00-\u0E7F\u0300-\u036F\u1AB0-\u1AFF\u1DC0-\u1DFF\u20D0-\u20FF\uFE20-\uFE2F]*([\s\(\)\.\-_'\u2018\u2019]*[a-zA-Z0-9_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u01FF\u0100-\u017F\u0180-\u024F\u1E00-\u1EFF\u0400-\u04FF\u0500-\u052F\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FFF\uAC00-\uD7AF\u0E00-\u0E7F][a-zA-Z0-9_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u01FF\u0100-\u017F\u0180-\u024F\u1E00-\u1EFF\u0400-\u04FF\u0500-\u052F\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FFF\uAC00-\uD7AF\u0E00-\u0E7F\u0300-\u036F\u1AB0-\u1AFF\u1DC0-\u1DFF\u20D0-\u20FF\uFE20-\uFE2F]*)*[ \(\)\.\-_'\u2018\u2019]*$ description: The last name of the recipient. example: Doe phone: type: string description: |- The phone number that the gift will be sent to. ( at the beginning is optional). Format: E.164. example: '+1234567890' email: type: string pattern: >- ^(?=.{1,60}$)(?!.*[.]{2})(?!\.)[a-zA-Z0-9._%+\-\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u01FF\u0100-\u017F\u0180-\u024F']+(?- An optional unique identifier for the gift sending, used to avoid duplicated gifts sending to the same recipients when not intending to. For example, if you implement a retry mechanism and want to avoid sending the same gift. example: abc123 externalId: type: string description: The id of the recipient in your own system. example: '1234567890' required: - firstname additionalProperties: false description: The gift recipient object. example: firstname: John lastname: Doe externalId: '1234567890' phone: '+1234567890' email: example@domain.com key: abc123 securitySchemes: CompanyLevelAuthentication: type: apiKey in: header name: X-Api-Key description: > ## Company Level Authentication Company level authentication provides access to all resources under your company, including accounts, campaigns, gifts, and recipients. ### Getting Your API Key 1. **Create an API Key**: Use the `POST /v2/authentication/apiKeys` endpoint to generate a new API key 2. **Set Expiration**: Choose from 30, 60, 90, or 180 days (default: 90 days) 3. **Optional mTLS**: Enable mutual TLS for enhanced security 4. **Name Your Key**: Provide a descriptive name for easy identification ### Using Your API Key Include your API key in the `X-Api-Key` header for every request: ``` X-Api-Key: YOUR_24_CHARACTER_API_KEY ``` ### API Key Management - **Maximum Keys**: Up to 3 active API keys per company - **Rotation**: Delete old keys before creating new ones when at the limit - **Security**: Keys are hashed and cannot be retrieved after creation ### Enhanced Security (mTLS) For production environments, enable mutual TLS authentication: 1. Set `enforceMtls: true` when creating the API key 2. Contact support to obtain your client certificates 3. Use the mTLS endpoint: `https://mtls-api.snappy.com/public-api` BearerAuthentication: type: http scheme: bearer bearerFormat: JWT description: >- Bearer authentication provides access to all resources under your company, including accounts, campaigns, gifts, and recipients. ````