openapi: 3.0.3 info: title: Related Visitors API v3 (deprecated) description: > > 🚧 Deprecation Notice > > This version of Server API is marked as deprecated starting on **Jan 7th 2026** and will be fully defunct on **Jan 7th 2027** according to our [API Deprecation Policy](https://docs.fingerprint.com/reference/api-deprecation-policy). If you still use this version, please follow our [migration guide](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) to migrate from this deprecated version to the new one. Use this API to unify and personalize the experience for your anonymous users who visit your website from regular and in-app browsers. version: '1.0' contact: name: Fingerprint Support email: support@fingerprint.com tags: - name: Related Visitors description: > Find visitor IDs that originated from a different browser on the same mobile device. servers: - url: https://api.fpjs.io description: Recommended if your customer base is primarily in the Americas. - url: https://eu.api.fpjs.io description: Recommended if your customer base is primarily in Europe. - url: https://ap.api.fpjs.io description: Recommended if your customer base is primarily in the APAC region. security: - ApiKeyHeader: [] - ApiKeyQuery: [] paths: /related-visitors: get: tags: - Related Visitors operationId: getRelatedVisitors summary: Get Related Visitors description: > > 🚧 Deprecation Notice > > This version of Server API is marked as deprecated starting on **Jan 7th 2026** and will be fully removed on **Jan 7th 2027** according to our [API Deprecation Policy](https://docs.fingerprint.com/reference/api-deprecation-policy). Related visitors API lets you link web visits and in-app browser visits that originated from the same mobile device. It searches the past 6 months of identification events to find the visitor IDs that belong to the same mobile device as the given visitor ID. ⚠️ Please note that this API is not enabled by default and is billable separately. ⚠️ If you would like to use Related visitors API, please contact our [support team](https://fingerprint.com/support). To learn more, see [Related visitors API reference](https://docs.fingerprint.com/reference/related-visitors-api). parameters: - name: visitor_id in: query required: true schema: type: string description: >- The [visitor ID](https://docs.fingerprint.com/reference/v3/js-agent-get-function#visitorid) for which you want to find the other visitor IDs that originated from the same mobile device. responses: '200': description: OK. content: application/json: schema: $ref: '#/components/schemas/RelatedVisitorsResponse' examples: 200-success-empty-response: summary: Success, empty response value: relatedVisitors: [] 200-success-response: summary: Success response value: relatedVisitors: - visitorId: NtCUJGceWX9RpvSbhvOm - visitorId: 25ee02iZwGxeyT0jMNkZ '400': description: >- Bad request. The visitor ID parameter is missing or in the wrong format. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: 400-visitor-id-required: summary: >- Error response when the request does not include a visitor ID. value: error: code: RequestCannotBeParsed message: visitor id is required 400-visitor-id-invalid: summary: Error response when the visitor ID is incorrectly formatted. value: error: code: RequestCannotBeParsed message: invalid visitor id '403': description: Forbidden. Access to this API is denied. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: 403-token-required: summary: Error response when the secret API key was not provided. value: error: code: TokenRequired message: secret key is required 403-token-not-found: summary: >- Error response when the provided secret API key does not exist. value: error: code: TokenNotFound message: secret key is not found 403-wrong-region: summary: >- Error response when the API region is different from the region, the calling application is configured with. value: error: code: WrongRegion message: wrong region 403-subscription-not-active: summary: Error response when the subscription is not active. value: error: code: SubscriptionNotActive message: forbidden 403-feature-not-enabled: summary: >- Error response when this feature is not enabled for a subscription. value: error: code: FeatureNotEnabled message: feature not enabled '404': description: >- Not found. The visitor ID cannot be found in this application's data. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: 404-visitor-not-found: summary: >- Error response when the visitor ID cannot be found in this application's data. value: error: code: VisitorNotFound message: visitor not found '429': description: Too Many Requests. The request is throttled. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: 429-too-many-requests: summary: >- Error response when the limit on the provided secret API key requests per second has been exceeded. value: error: code: TooManyRequests message: too many requests components: securitySchemes: ApiKeyHeader: type: apiKey in: header name: Auth-API-Key ApiKeyQuery: type: apiKey in: query name: api_key schemas: RelatedVisitor: type: object additionalProperties: false required: - visitorId properties: visitorId: type: string description: >- Visitor ID of a browser that originates from the same mobile device as the input visitor ID. RelatedVisitorsResponse: type: object additionalProperties: false required: - relatedVisitors properties: relatedVisitors: type: array items: $ref: '#/components/schemas/RelatedVisitor' ErrorCode: type: string enum: - RequestCannotBeParsed - TokenRequired - TokenNotFound - SubscriptionNotActive - WrongRegion - FeatureNotEnabled - RequestNotFound - VisitorNotFound - TooManyRequests - 429 Too Many Requests - StateNotReady - Failed description: | Error code: * `RequestCannotBeParsed` - the query parameters or JSON payload contains some errors that prevented us from parsing it (wrong type/surpassed limits). * `TokenRequired` - `Auth-API-Key` header is missing or empty. * `TokenNotFound` - no Fingerprint application found for specified secret key. * `SubscriptionNotActive` - Fingerprint application is not active. * `WrongRegion` - server and application region differ. * `FeatureNotEnabled` - this feature (for example, Delete API) is not enabled for your application. * `RequestNotFound` - the specified request ID was not found. It never existed, expired, or it has been deleted. * `VisitorNotFound` - The specified visitor ID was not found. It never existed or it may have already been deleted. * `TooManyRequests` - the limit on secret API key requests per second has been exceeded. * `429 Too Many Requests` - the limit on secret API key requests per second has been exceeded. * `StateNotReady` - The event specified with request id is not ready for updates yet. Try again. This error happens in rare cases when update API is called immediately after receiving the request id on the client. In case you need to send information right away, we recommend using the JS agent API instead. * `Failed` - internal server error. Error: type: object additionalProperties: false required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string ErrorResponse: type: object additionalProperties: false required: - error properties: error: $ref: '#/components/schemas/Error'