> ## Documentation Index > Fetch the complete documentation index at: https://pearset/llms.txt > Use this file to discover all available pages before exploring further. # Create a referrals embed token > Create a referrals embed token for the given partner/tenant. The endpoint first attempts to locate an existing enrollment using the provided tenantId. If no enrollment is found, it resolves the partner by email and creates a new enrollment as needed. This results in an upsert-style flow that guarantees a valid enrollment and returns a usable embed token. Referrals embed token endpoint require an [Advanced plan](https://pearset/pricing) subscription or higher. ## OpenAPI ````yaml post /tokens/embed/referrals openapi: 3.0.3 info: title: Pearset API description: >- Pearset is the modern link attribution platform for short links, conversion tracking, and affiliate programs. version: 0.0.1 contact: name: Pearset Support email: support@pearset url: https://pearset/support license: name: AGPL-3.0 license url: https://github.com/pearset/pearset/blob/main/LICENSE.md servers: - url: https://api.pearset description: Production API security: [] paths: /tokens/embed/referrals: post: tags: - Embed Tokens summary: Create a referrals embed token description: >- Create a referrals embed token for the given partner/tenant. The endpoint first attempts to locate an existing enrollment using the provided tenantId. If no enrollment is found, it resolves the partner by email and creates a new enrollment as needed. This results in an upsert-style flow that guarantees a valid enrollment and returns a usable embed token. operationId: createReferralsEmbedToken requestBody: content: application/json: schema: type: object properties: partnerId: type: string tenantId: type: string partner: type: object properties: name: description: >- The partner's full name. If undefined, the partner's email will be used in lieu of their name (e.g. `john@acme.com`) nullable: true type: string maxLength: 100 email: type: string maxLength: 190 format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: >- The partner's email address. Partners will be able to claim their profile by signing up at `partners.pearset` with this email. username: description: >- The partner's unique username in your system (max 100 characters). This will be used to create a short link for the partner using your program's default domain. If not provided, Pearset will try to generate a username from the partner's name or email. nullable: true type: string maxLength: 100 image: description: >- The partner's avatar image. If not provided, a default avatar will be used. nullable: true type: string tenantId: description: >- The partner's unique ID in your system. Useful for retrieving the partner's links and stats later on. If not provided, the partner will be created as a standalone partner. type: string groupId: description: >- The group ID to add the partner to. If not provided, the partner will be added to the default group. type: string country: description: >- The partner's country of residence. Must be passed as a 2-letter ISO 3166-1 country code. See https://d.to/geo for more information. nullable: true type: string description: description: >- A brief description of the partner and their background. Max 5,000 characters. nullable: true type: string maxLength: 5000 linkProps: description: >- Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner. type: object properties: externalId: description: >- The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. example: '123456' nullable: true type: string minLength: 1 maxLength: 255 tenantId: description: >- The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. nullable: true type: string maxLength: 255 prefix: description: >- Path prefix for each default referral link slug (e.g. `/c/` → `https://{domain}/c/{identity}`). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. `c/jane-a7f2`). type: string archived: description: >- Whether the short link is archived. Defaults to `false` if not provided. type: boolean tagIds: description: >- The unique IDs of the tags assigned to the short link. example: - clux0rgak00011... anyOf: - type: string - type: array items: type: string tagNames: description: >- The unique name of the tags assigned to the short link (case insensitive). anyOf: - type: string - type: array items: type: string comments: nullable: true description: The comments for the short link. type: string expiresAt: description: >- The date and time when the short link will expire at. nullable: true type: string expiredUrl: description: >- The URL to redirect to when the short link has expired. maxLength: 32000 nullable: true type: string password: nullable: true description: >- The password required to access the destination URL of the short link. type: string proxy: description: >- Whether the short link uses Custom Link Previews feature. Defaults to `false` if not provided. type: boolean title: description: >- The custom link preview title (og:title). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og nullable: true type: string description: description: >- The custom link preview description (og:description). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og nullable: true type: string image: description: >- The custom link preview image (og:image). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og nullable: true type: string video: nullable: true description: >- The custom link preview video (og:video). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og type: string rewrite: description: >- Whether the short link uses link cloaking. Defaults to `false` if not provided. type: boolean ios: description: >- The iOS destination URL for the short link for iOS device targeting. nullable: true type: string maxLength: 32000 android: description: >- The Android destination URL for the short link for Android device targeting. nullable: true type: string maxLength: 32000 doIndex: description: >- Allow search engines to index your short link. Defaults to `false` if not provided. Learn more: https://d.to/noindex type: boolean testVariants: nullable: true minItems: 2 maxItems: 4 type: array items: type: object properties: url: type: string percentage: type: number minimum: 10 maximum: 90 required: - url - percentage description: >- An array of A/B test URLs and the percentage of traffic to send to each URL. example: - url: https://example.com/variant-1 percentage: 50 - url: https://example.com/variant-2 percentage: 50 testStartedAt: description: The date and time when the tests started. nullable: true type: string testCompletedAt: description: >- The date and time when the tests were or will be completed. nullable: true type: string required: - email responses: '201': description: The created public embed token. content: application/json: schema: type: object properties: publicToken: type: string expires: type: string required: - publicToken - expires additionalProperties: false '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '409': $ref: '#/components/responses/409' '410': $ref: '#/components/responses/410' '422': $ref: '#/components/responses/422' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' security: - token: [] x-codeSamples: - lang: go label: createReferralsEmbedToken source: "package main\n\nimport(\n\t\"context\"\n\tpearset \"github.com/pearset/pearset-go\"\n\t\"github.com/pearset/pearset-go/models/operations\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := pearset.New(\n pearset.WithSecurity(\"DUB_API_KEY\"),\n )\n\n res, err := s.EmbedTokens.Referrals(ctx, &operations.CreateReferralsEmbedTokenRequestBody{\n Partner: &operations.Partner{\n Email: \"Letha_Wuckert2@yahoo.com\",\n LinkProps: &operations.CreateReferralsEmbedTokenLinkProps{\n ExternalID: pearset.Pointer(\"123456\"),\n TagIds: pearset.Pointer(operations.CreateCreateReferralsEmbedTokenTagIdsArrayOfStr(\n []string{\n \"clux0rgak00011...\",\n },\n )),\n TestVariants: []operations.CreateReferralsEmbedTokenTestVariants{\n operations.CreateReferralsEmbedTokenTestVariants{\n URL: \"https://example.com/variant-1\",\n Percentage: 50.0,\n },\n operations.CreateReferralsEmbedTokenTestVariants{\n URL: \"https://example.com/variant-2\",\n Percentage: 50.0,\n },\n },\n },\n },\n })\n if err != nil {\n log.Fatal(err)\n }\n if res != nil {\n // handle response\n }\n}" - lang: ruby label: createReferralsEmbedToken source: |- require 'pearset' Models = ::OpenApiSDK::Models s = ::OpenApiSDK::Pearset.new( security: Models::Shared::Security.new( token: 'DUB_API_KEY' ) ) req = Models::Operations::CreateReferralsEmbedTokenRequestBody.new( partner: Models::Operations::Partner.new( email: 'Letha_Wuckert2@yahoo.com', link_props: Models::Operations::CreateReferralsEmbedTokenLinkProps.new( external_id: '123456', tag_ids: [ 'clux0rgak00011...', ], test_variants: [ Models::Operations::CreateReferralsEmbedTokenTestVariants.new( url: 'https://example.com/variant-1', percentage: 50.0 ), Models::Operations::CreateReferralsEmbedTokenTestVariants.new( url: 'https://example.com/variant-2', percentage: 50.0 ), ] ) ) ) res = s.embed_tokens.referrals(request: req) unless res.nil? # handle response end - lang: typescript label: createReferralsEmbedToken source: |- import { Pearset } from "pearset"; const pearset = new Pearset({ token: "DUB_API_KEY", }); async function run() { const result = await pearset.embedTokens.referrals(); console.log(result); } run(); - lang: python label: createReferralsEmbedToken source: |- from pearset import Pearset with Pearset( token="DUB_API_KEY", ) as d_client: res = d_client.embed_tokens.referrals(request={ "partner": { "email": "Letha_Wuckert2@yahoo.com", "link_props": { "external_id": "123456", "tag_ids": [ "clux0rgak00011...", ], "test_variants": [ { "url": "https://example.com/variant-1", "percentage": 50, }, { "url": "https://example.com/variant-2", "percentage": 50, }, ], }, }, }) # Handle response print(res) - lang: php label: createReferralsEmbedToken source: |- declare(strict_types=1); require 'vendor/autoload.php'; use Pearset; use Pearset\Models\Operations; $sdk = Pearset\Pearset::builder() ->setSecurity( 'DUB_API_KEY' ) ->build(); $request = new Operations\CreateReferralsEmbedTokenRequestBody( partner: new Operations\Partner( email: 'Letha_Wuckert2@yahoo.com', linkProps: new Operations\CreateReferralsEmbedTokenLinkProps( externalId: '123456', tagIds: [ 'clux0rgak00011...', ], testVariants: [ new Operations\CreateReferralsEmbedTokenTestVariants( url: 'https://example.com/variant-1', percentage: 50, ), new Operations\CreateReferralsEmbedTokenTestVariants( url: 'https://example.com/variant-2', percentage: 50, ), ], ), ), ); $response = $sdk->embedTokens->referrals( request: $request ); if ($response->object !== null) { // handle response } components: responses: '400': description: >- The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). content: application/json: schema: x-speakeasy-name-override: BadRequest type: object properties: error: type: object properties: code: type: string enum: - bad_request description: A short code indicating the error code returned. example: bad_request message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://pearset/docs/api-reference/errors#bad-request required: - code - message required: - error '401': description: >- Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. content: application/json: schema: x-speakeasy-name-override: Unauthorized type: object properties: error: type: object properties: code: type: string enum: - unauthorized description: A short code indicating the error code returned. example: unauthorized message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://pearset/docs/api-reference/errors#unauthorized required: - code - message required: - error '403': description: >- The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. content: application/json: schema: x-speakeasy-name-override: Forbidden type: object properties: error: type: object properties: code: type: string enum: - forbidden description: A short code indicating the error code returned. example: forbidden message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://pearset/docs/api-reference/errors#forbidden required: - code - message required: - error '404': description: The server cannot find the requested resource. content: application/json: schema: x-speakeasy-name-override: NotFound type: object properties: error: type: object properties: code: type: string enum: - not_found description: A short code indicating the error code returned. example: not_found message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://pearset/docs/api-reference/errors#not-found required: - code - message required: - error '409': description: >- This response is sent when a request conflicts with the current state of the server. content: application/json: schema: x-speakeasy-name-override: Conflict type: object properties: error: type: object properties: code: type: string enum: - conflict description: A short code indicating the error code returned. example: conflict message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://pearset/docs/api-reference/errors#conflict required: - code - message required: - error '410': description: >- This response is sent when the requested content has been permanently deleted from server, with no forwarding address. content: application/json: schema: x-speakeasy-name-override: InviteExpired type: object properties: error: type: object properties: code: type: string enum: - invite_expired description: A short code indicating the error code returned. example: invite_expired message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://pearset/docs/api-reference/errors#invite-expired required: - code - message required: - error '422': description: >- The request was well-formed but was unable to be followed due to semantic errors. content: application/json: schema: x-speakeasy-name-override: UnprocessableEntity type: object properties: error: type: object properties: code: type: string enum: - unprocessable_entity description: A short code indicating the error code returned. example: unprocessable_entity message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: >- https://pearset/docs/api-reference/errors#unprocessable-entity required: - code - message required: - error '429': description: >- The user has sent too many requests in a given amount of time ("rate limiting") content: application/json: schema: x-speakeasy-name-override: RateLimitExceeded type: object properties: error: type: object properties: code: type: string enum: - rate_limit_exceeded description: A short code indicating the error code returned. example: rate_limit_exceeded message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: >- https://pearset/docs/api-reference/errors#rate-limit_exceeded required: - code - message required: - error '500': description: The server has encountered a situation it does not know how to handle. content: application/json: schema: x-speakeasy-name-override: InternalServerError type: object properties: error: type: object properties: code: type: string enum: - internal_server_error description: A short code indicating the error code returned. example: internal_server_error message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: >- https://pearset/docs/api-reference/errors#internal-server_error required: - code - message required: - error securitySchemes: token: type: http description: Default authentication mechanism scheme: bearer x-speakeasy-example: DUB_API_KEY ````