{
  "openapi": "3.0.3",
  "info": {
    "title": "Related Visitors API v3 (deprecated)",
    "description": "> 🚧 Deprecation Notice\n>\n> 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://dev.fingerprint.com/reference/api-deprecation-policy). If you still use this version, please follow our [migration guide](https://dev.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) to migrate from this deprecated version to the new one.\n\nUse this API to unify and personalize the experience for your anonymous users who visit your website from regular and in-app browsers.\n",
    "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.\n"
    }
  ],
  "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\n>\n> 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://dev.fingerprint.com/reference/api-deprecation-policy).\n\nRelated visitors API lets you link web visits and in-app browser visits that originated from the same mobile device.\nIt 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.\n\n⚠️ Please note that this API is not enabled by default and is billable separately. ⚠️\n\nIf you would like to use Related visitors API, please contact our [support team](https://fingerprint.com/support).\nTo learn more, see [Related visitors API reference](https://dev.fingerprint.com/reference/related-visitors-api).\n",
        "parameters": [
          {
            "name": "visitor_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The [visitor ID](https://dev.fingerprint.com/reference/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:\n * `RequestCannotBeParsed` - the query parameters or JSON payload contains some errors \n          that prevented us from parsing it (wrong type/surpassed limits).\n * `TokenRequired` - `Auth-API-Key` header is missing or empty.\n * `TokenNotFound` - no Fingerprint application found for specified secret key.\n * `SubscriptionNotActive` - Fingerprint application is not active.\n * `WrongRegion` - server and application region differ.\n * `FeatureNotEnabled` - this feature (for example, Delete API) is not enabled for your application.\n * `RequestNotFound` - the specified request ID was not found. It never existed, expired, or it has been deleted.\n * `VisitorNotFound` - The specified visitor ID was not found. It never existed or it may have already been deleted.\n * `TooManyRequests` - the limit on secret API key requests per second has been exceeded.\n * `429 Too Many Requests` - the limit on secret API key requests per second has been exceeded.\n * `StateNotReady` - The event specified with request id is\n          not ready for updates yet. Try again.\n          This error happens in rare cases when update API is called immediately\n          after receiving the request id on the client. In case you need to send\n          information right away, we recommend using the JS agent API instead.\n * `Failed` - internal server error.\n"
      },
      "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"
          }
        }
      }
    }
  }
}