{ "openapi": "3.0.1", "info": { "title": "Identity Resolution API - PII to Pseudonymous Person ID", "description": "Resolve names, postal addresses, email addresses and phone numbers, plaintext or hashed, to a stable pseudonymous person identifier, so the same person can be recognised across systems without those systems exchanging contact details. Returns the match level and components. Pay per result.", "version": "0.1", "x-build-id": "q4iF7xcncfjb7nXUR" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~identity-graph-resolution-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-identity-graph-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-graph-resolution-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-identity-graph-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-graph-resolution-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-identity-graph-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 send", "enum": [ "match", "lookup" ], "type": "string", "description": "Match takes plaintext contact details and does its own normalisation and fuzzy matching, working down a cascade from the strongest combination to the weakest. Lookup takes values you have already hashed, which never leave your side in the clear.", "default": "match" }, "emails": { "title": "Email addresses", "type": "array", "description": "In match mode, addresses to resolve, one per line. Email on its own is a valid combination for this provider and sits at step six of its match cascade. Remember the batch floor: at least 100 records must reach the provider in one run.", "items": { "type": "string" } }, "phones": { "title": "Phone numbers", "type": "array", "description": "In match mode, numbers to resolve, one per line. The provider wants ten digits and nothing else; a leading country code of 1 is stripped for you and anything that is not ten digits after that is refused before it can spoil the batch.", "items": { "type": "string" } }, "records": { "title": "Records", "type": "array", "description": "In match mode, full records as JSON objects, when you have more than an address or a number. Accepted keys: name or firstName, middleName, lastName and generationalSuffix; streetAddress or primaryNumber, preDirectional, street, streetSuffix, postDirectional, unitDesignator and secondaryNumber; plus city, state, zipCode, email and phone. Give a name whole or in parts, never both, and the same for a street address: the provider refuses a record that does both, so this actor refuses it first." }, "hashes": { "title": "Hashed values", "type": "array", "description": "In lookup mode, the digests to resolve, one per line, all of the same algorithm. Digests of the wrong length for the chosen algorithm are refused here rather than sent, because a single bad element can cost you the whole batch.", "items": { "type": "string" } }, "hashType": { "title": "Hash algorithm", "enum": [ "md5", "sha1", "sha256" ], "type": "string", "description": "Which algorithm produced the digests above. SHA-256 and MD5 apply to hashed email addresses; SHA-1 also covers hashed phone numbers. Getting this wrong reads as every value being unknown rather than as an error, which is why the length is checked against it before anything is sent.", "default": "sha256" }, "matchLimit": { "title": "Identifiers per record", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many identifiers to return for one record, from 1 to 10. Anything above 1 needs a permission the provider grants separately, so leave it at 1 unless you know your account has it. Note that asking for more than one also stops the provider reporting whether a match was distinct.", "default": 1 }, "distinctMatchesOnly": { "title": "Keep only distinct matches", "type": "boolean", "description": "Keep only rows where the provider found a single clear best match rather than several equally good ones. This is the strictest quality filter available here. It only means anything when you are asking for one identifier per record, because the flag is not reported otherwise.", "default": false }, "maxMatchConfidence": { "title": "Weakest match to accept", "minimum": 0, "maximum": 8, "type": "integer", "description": "The provider reports which step of its cascade produced the match, from 1 for name, address and postal code down to 8 for name and postal code alone. A lower number is a stronger match, so this is a floor on quality: set 3 to accept only matches made on a name together with an address, an email or a phone. Leave at zero to accept every level.", "default": 0 }, "requiredComponents": { "title": "Require these components in the match", "type": "array", "description": "Keep only rows where every one of these contributed to the match. Use it when a particular field is the one you trust: requiring the email component drops matches that were made on a name and a postal code alone.", "items": { "type": "string", "enum": [ "name", "streetAddress", "zipCode", "businessName", "phoneNumber", "emailAddress" ], "enumTitles": [ "Name", "Street address", "Postal code", "Business name", "Phone number", "Email address" ] }, "default": [] }, "completeNamesOnly": { "title": "Require the whole name to have matched", "type": "boolean", "description": "Drop rows where only part of the name was used to reach the match. Partial name matching is what lets the provider connect a record for Bob to a record for Robert, which is useful and is also where the false positives live.", "default": false }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 600, "type": "integer", "description": "Pace the run so it stays under whatever rate your contract allows. Each request here carries up to a thousand records, so this number is far smaller than it looks.", "default": 60 }, "skipNotFound": { "title": "Skip records with no identifier", "type": "boolean", "description": "Leave results with no identifier, and inputs refused before they were sent, out of the dataset. Off by default: the count of unresolved records is how you measure the coverage of your own data, and the opted-out flag is worth keeping. Misses are never charged for either way.", "default": false }, "maxResults": { "title": "Maximum results", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Stop after this many rows. Note that this cannot make a batch smaller: the provider refuses anything under 100 records, so a lower cap here still sends the full batch and simply writes fewer rows.", "default": 1000 }, "clientId": { "title": "Client id", "type": "string", "description": "The client id of your own service account with the identity provider, issued by your account representative. Stored as a secret and never logged." }, "apiKey": { "title": "Client secret", "type": "string", "description": "The client secret that goes with the id above. It is exchanged for a short-lived access token, which the actor refreshes before it expires rather than after, because this provider reports an expired token the same way it reports a missing permission. Stored as a 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 } } } } } } } } } }