{ "openapi": "3.0.1", "info": { "title": "Identity Resolution API - Reverse Email and Phone Lookup", "description": "Resolve an email address, phone number, name, username or social profile URL into the person behind it, with names, emails, phones, addresses, jobs, education, social profiles and a confidence score on every match. Only pay for answers that contain the fields you asked for. Pay per result.", "version": "0.1", "x-build-id": "H8ih0Gh02TbzzcvTm" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~identity-resolution-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-identity-resolution-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/nabeelbaghoor~identity-resolution-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-identity-resolution-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/nabeelbaghoor~identity-resolution-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-identity-resolution-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "What to search by", "enum": [ "email", "phone", "name", "lead", "username", "profileUrl", "vin", "searchPointer" ], "type": "string", "description": "Every search resolves an identifier into the person behind it. Email, phone, username, profile URL and VIN each take a single identifier per row. Name search takes a full name, and is worth narrowing with a country, state or city. Combined reads several lists row by row so one row is one person, which is what a name plus a phone or a name plus an address search needs. Search pointer follows up a candidate returned by an earlier run.", "default": "email" }, "emails": { "title": "Email addresses", "type": "array", "description": "Email addresses, one per line. An address pasted inside a longer string, such as a mail header or a name and address pair, is extracted before the request. Used by email search, and as the email half of a combined lookup.", "items": { "type": "string" } }, "phones": { "title": "Phone numbers", "type": "array", "description": "Phone numbers, one per line, in international format such as +12065550100. Used by phone search, and as the phone half of a combined lookup.", "items": { "type": "string" } }, "names": { "title": "Full names", "type": "array", "description": "Full names, one per line. A two or three word name is split into first, middle and last before the request, which matches better than sending the whole string; anything else is sent whole. Used by name search, and as the name half of a combined lookup.", "items": { "type": "string" } }, "addresses": { "title": "Postal addresses", "type": "array", "description": "Postal addresses, one per line, written as one line each, in the same order as the names. A full address including a house number is enough to search on by itself. Combined lookups only.", "items": { "type": "string" } }, "usernames": { "title": "Usernames and user ids", "type": "array", "description": "Screen names, one per line, minimum three characters. Target a specific service by writing it as name@service, for example janedoe@facebook. A value written as digits then a service, such as 11231@facebook, is sent as a user id instead, which is the separate parameter the provider defines for it.", "items": { "type": "string" } }, "profileUrls": { "title": "Social profile URLs", "type": "array", "description": "Profile URLs on supported services, one per line, such as a LinkedIn, Facebook or Twitter profile. The provider parses each URL down to the username or user id behind it.", "items": { "type": "string" } }, "vins": { "title": "Vehicle identification numbers", "type": "array", "description": "Vehicle identification numbers, one per line, to resolve to the person on record for the vehicle.", "items": { "type": "string" } }, "searchPointers": { "title": "Search pointers", "type": "array", "description": "Search pointers, one per line, copied from the searchPointer column of an earlier run. A pointer expands a thin candidate into the full record. Pointers are long, so they are sent in the request body rather than on the URL.", "items": { "type": "string" } }, "country": { "title": "Country", "type": "string", "description": "Two letter ISO 3166 country code applied to every search in the run, for example US. Narrowing a name search by country is the single biggest thing you can do to reduce the candidate list." }, "state": { "title": "State or province", "type": "string", "description": "State or province code applied to every search in the run, for example WA. Recognised for the United States, Canada, Great Britain and Australia. A United States state with no country set implies the United States." }, "city": { "title": "City", "type": "string", "description": "City applied to every search in the run." }, "matchRequirements": { "title": "Only pay for results that contain", "type": "array", "description": "Require these fields to be present in the answer. This is the setting that controls cost: the provider evaluates the requirement before it charges, so a search that comes back without what you asked for returns empty and is not billed. Asking for an email when you only need emails is the difference between paying for every lookup and paying for the ones that worked.", "items": { "type": "string", "enum": [ "name", "name.first", "name.last", "address", "phone", "phone.mobile", "phone.work_phone", "phone.voip", "email", "email.personal", "email.work", "job", "education", "image", "username", "user_id", "dob", "url", "gender", "language", "origin_country", "vehicle", "social_profile" ], "enumTitles": [ "Any name", "First name", "Last name", "Postal address", "Any phone", "Mobile phone", "Work phone", "VOIP phone", "Any email", "Personal email", "Work email", "Job", "Education", "Image", "Username", "User id", "Date of birth", "Profile URL", "Gender", "Language", "Origin country", "Vehicle", "Social profile" ] }, "default": [] }, "matchRequirementsJoin": { "title": "Require all or any of them", "enum": [ "all", "any" ], "type": "string", "description": "Whether every field above has to be present, or just one of them. Requiring all of a long list is how a run ends up paying for almost nothing; requiring any of two or three is usually what you want.", "default": "all" }, "matchRequirementsNewDataOnly": { "title": "Only count data you did not already have", "type": "boolean", "description": "Require the fields above to be data that was not in your own query. Searching by an email and requiring a new email is how you find a person's other addresses rather than paying to be told the one you already had.", "default": false }, "sourceCategoryRequirements": { "title": "Only pay for results from these source types", "type": "array", "description": "Require the answer to include data from these kinds of source. Like the field requirement above, this is evaluated before charging, so a person found only in sources you do not care about is not billed.", "items": { "type": "string", "enum": [ "personal_profiles", "professional_and_business", "public_records", "contact_details", "email_address", "background_reports", "school_and_classmates", "media", "publications", "web_pages" ], "enumTitles": [ "Personal profiles, such as social networks", "Professional and business directories", "Public records", "Contact detail directories", "Email address directories", "Background report providers", "School and classmate sites", "Media sites", "Publications", "Other web pages" ] }, "default": [] }, "sourceCategoryRequirementsJoin": { "title": "Require all or any of those source types", "enum": [ "all", "any" ], "type": "string", "description": "Whether the answer has to draw on every source type selected, or just one of them.", "default": "any" }, "topMatch": { "title": "Only accept a confident single match", "type": "boolean", "description": "Return the single best high ranking person or nothing at all, never a list of candidates. This is the setting for automated enrichment, where a wrong person is worse than no person.", "default": false }, "minimumMatch": { "title": "Minimum match score", "minimum": 0, "maximum": 100, "type": "integer", "description": "Only return people whose confidence score is at least this, on a 0 to 100 scale here and 0 to 1 at the provider. Set 100 to accept only single perfect matches. Applied by the provider, so it also keeps candidates you would have discarded out of the bill." }, "minimumProbability": { "title": "Minimum probability for inferred data", "minimum": 0, "maximum": 100, "type": "integer", "description": "How confident the provider has to be before it includes a field it inferred rather than observed, on a 0 to 100 scale. The provider default is 90." }, "inferPersons": { "title": "Allow fully inferred people", "type": "boolean", "description": "Allow people assembled purely by statistical inference from your query rather than found in a source. Off by default, and worth leaving off unless you are deliberately exploring.", "default": false }, "liveFeeds": { "title": "Use live data sources", "type": "boolean", "description": "Query live sources as well as the index. Adds roughly two to three percent more data at the cost of one to two seconds per search, and a lower ceiling on requests per second. On by default at the provider.", "default": true }, "hideSponsored": { "title": "Hide sponsored results", "type": "boolean", "description": "Leave out results whose extra data sits behind a third party paywall.", "default": false }, "showSources": { "title": "Include the source layer", "enum": [ "false", "matching", "all" ], "type": "string", "description": "Return where each answer came from. Matching returns only the sources used to build the person, which is the useful setting for provenance and auditing. All also returns sources that were considered but not used.", "default": "false" }, "expandPossiblePersons": { "title": "Expand candidates into full records", "type": "boolean", "description": "When the provider answers with a list of candidates rather than one person, follow each candidate's search pointer to pull its full record. Off by default because each expansion is a second billable search at the provider as well as another charged row here.", "default": false }, "maxExpansionsPerSearch": { "title": "Maximum candidates to expand per search", "minimum": 1, "maximum": 50, "type": "integer", "description": "Ceiling on how many candidates from a single search get expanded. Keeps one ambiguous name from turning into fifty lookups.", "default": 3 }, "skipPossibleMatches": { "title": "Drop unexpanded candidates", "type": "boolean", "description": "Leave out rows that are candidates rather than confident matches. Consider setting the confident single match option above instead, which stops the provider from returning them at all.", "default": false }, "minMatchScore": { "title": "Drop rows below this match score", "minimum": 0, "maximum": 100, "type": "integer", "description": "A second, local pass on the confidence score, on the same 0 to 100 scale, applied after the provider answers. The provider side minimum above is the one that saves money; this one only trims the dataset." }, "requireEmail": { "title": "Drop rows with no email address", "type": "boolean", "description": "Skip resolved people who carry no email address. The match requirement above does the same thing at the provider and without being charged, so prefer it where you can.", "default": false }, "requirePhone": { "title": "Drop rows with no phone number", "type": "boolean", "description": "Skip resolved people who carry no phone number.", "default": false }, "requireJob": { "title": "Drop rows with no job", "type": "boolean", "description": "Skip resolved people who carry no job title or employer.", "default": false }, "requireSocialProfile": { "title": "Drop rows with no social profile", "type": "boolean", "description": "Skip resolved people who carry no profile URL.", "default": false }, "skipNotFound": { "title": "Skip searches that match nobody", "type": "boolean", "description": "By default a search that matched nobody is still written, with found set to false and the reason on the row, so a list can be reconciled against what went in. Switch this on to leave those rows out entirely. Rows with no match are never charged for either way.", "default": false }, "maxResults": { "title": "Maximum results", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Stop after this many rows. Note that one ambiguous search can return several candidate rows.", "default": 100 }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 1200, "type": "integer", "description": "How fast to call the provider. Requests are spaced evenly rather than sent in bursts, which is what keeps a long list from bunching up against the per second limiter. Lower this if your plan has a tighter ceiling, and lower it further when live data sources are on.", "default": 300 }, "apiKey": { "title": "API key", "type": "string", "description": "Your own API key for the identity data provider this actor calls. The actor never ships a key: you bring yours, the run uses it, and it is stored encrypted. Can also be supplied as the DATA_API_KEY environment secret." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }