Search

Infutor API – Identity Completion

Ayesha Akhtar
Ayesha Akhtar

Overview

InfutorData is a consumer data and insights company that specializes in helping marketers and the platforms they work with continuously maintain a real-time view of their consumers’ profiles and behaviors as they change over time.

With inbound leads, marketers often lack information on the consumer. The Infutor API helps you obtain the complete identity of the consumer in real-time, confirm and supplement consumer-provided data, and enrich your insights on each consumer with additional attributes.

Inputs

The Infutor API accepts the following inputs:

Input Field Description Required
FullName Full individual Name Optional*
FName First name, 15 characters max Required*
LName Last name, 20 characters max Required*
Address1 Address line 1, 64 characters max Required*
Address2 Address line 2, 64 characters max Optional
City City name, 28 characters max. Either City/State or Zip is required Required*
State 2 character state abbreviation. Either City/State or Zip is required Required*
Zip 5 digit numeric USPS zip code. Either City/State or Zip is required Required*
Phone1 10 digit numeric phone number (without spaces, dashes, or parentheses) Required*
Phone2 10 digit numeric 2nd phone number (without spaces, dashes, or parentheses) Optional
Email Email address, 100 characters max Required*

At a minimum, one of the following input combinations is required for processing:

  • Phone1
  • Phone2
  • Email
  • FName + LName
  • FullName
  • Address1 + Zip
  • Address1 + City + State

Authentication Protocol

The authentication layer of our API is recommended for protecting sensitive information and ensuring that data transmitted between your networks and Infutor systems are securely protected. This method is necessary for API security and can help to improve the user experience, all while protecting sensitive data.

Authentication can be enabled for your account as needed. In the instance that a query is sent to our API, an authentication header 'authorization: {token}' will be required with the token Infutor generates.

How Does It Work?

Infutor will make sure an authentication token is created and provided to you. The API will then require the customer to send a new authorization key in the API Request header which will include the token(s) Infutor generates.

Example Request

curl --location 'https://api.infutor.com/SingleQuery' \
--header 'Authorization: Bearer YOUR_AUTH_TOKEN_HERE' \
--form 'data="fname;JOHN|l_name;SMITH|address1;522 MERCURY DR|city;LOUISVILLE|state;KY|zip;40258|phone1;5024477026|email;john.smith@gmail.com"'

Notes

  • Replace YOUR_AUTH_TOKEN_HERE with the actual authorization token provided to you by Infutor.
  • The Authorization header is required for authentication and must be included in all API requests.
  • The data field uses a pipe-delimited (|) key-value format with semicolons (;) separating keys from values.
  • Ensure that there are no extra spaces in the request data, as formatting issues may result in failed or incomplete submissions.

Outputs

Please be aware that the API response will only include fields where data is available. If an attribute does not have a match or relevant value for a given request, it will be omitted from the response.

Also, the number of attributes returned may vary depending on the strength of the match:

  • When the data match is strong (matchLevel 1–2), you can expect a more complete set of fields in the response.
  • When the match is weak or partial (matchLevel 3–6), only a limited number of fields may be returned.

Because of this, the structure of the response may differ from one call to another. We recommend building your integration to handle flexible and dynamic responses where not all fields are guaranteed to be present.

Consumer Data

Output Field Description Return Values
matchLevel Indicates level of identity match to the Infutor Graph: 1 – individual level match, 2 – household level match, 3 – lower level match, 4 – name + multiple markers match, but name mismatched, 5 – match without demographics available, 6 – no match, but gender inferred from name 1–6
persistentId Synthetic PID, Unique individual. Encrypted value. 32 characters max
householdId Synthetic Household ID, Unique address + Last Name. Encrypted value. 100 characters max

Identity Completion

The Identity Completion service appends additional contact information including names, addresses, phone numbers, and email addresses associated with the matched consumer identity.

Output Field Description Return Values
FName Appended First Name 20 characters
LName Appended Last Name 20 characters
MName Appended Middle Initial 1 Character
BusName Appended Business Name 100 Characters
PreDir Appended Street Pre Direction: N, S, E, W, NE, SW, etc. 2 Characters
Street Appended Street name 28 characters
StrType Appended Street suffix: ST, AVE, BLVD, etc. 4 Characters
PostDir Appended Street Post Direction: N, S, E, W, NE, SW, etc. 4 Characters
AptType Appended Secondary Unit designator: Apt, Suite, etc. 2 Characters
AptNbr Appended Secondary Unit number 8 Characters
City Appended USPS City Name 28 Characters
State Appended USPS State abbreviation 2 Characters
Zip Appended numeric USPS Zip Code 5 Characters
Z4 Appended numeric USPS Zip+4 4 Characters
DPC Appended Delivery Point Code with check digit 3 Characters
CRTE Appended Carrier Route 4 Characters
CNTY Appended FIPS County Code 3 Characters
Z4Type Appended USPS Zip+4 type: F–Firm, G–General Delivery, H–High-rise/Business, P–PO Box, R–Rural Route, S–Street/Residential, Blank–Unknown F, G, H, P, R, S
DPV Appended Delivery Point Validation: Y–Confirmed (primary & secondary), D–Primary confirmed only (secondary missing), S–Primary confirmed, secondary unconfirmed, N–Both failed, Blank–Not presented Y, D, S, N
Deliverable Appended Deliverable flag Y, N, or Blank
ValDate Appended Last address validation date YYYYMMDD or YYYYMM
Phone Appended Phone (up to 3 additional phone numbers) 10 characters
PhoneType Appended Phone Type (up to 3): L–Landline, V–VoIP, W–Wireless, O–Other L, V, W, O
DID Direct Inward Dial Number Y or blank
RecType Appended Record Type: R–Residential, B–Business, P–Payphone, U–Unknown R, B, P, U
IDate Date phone record was first received YYYYMMDD
ODate Date phone record was last received as connected YYYYMMDD
TelcoName Name of original telephone company provider 100 Characters
Category Appended Matched Category: I–Individual, H–Household, A–Address, Z–Name/Zip I, H, A, Z
Email Appended Email (up to 3 additional emails) 100 Characters
Suppression A–Potential Traps, B–Syntax Errors, C–Hard Bounces, F–Traps, G–Do Not Email, H–Clean Email, V–Verified Deliverable A, B, C, F, G, H, V or blank
Url Appended URL – indicates the website where the consumer opted in to receive marketing emails 100 Characters
PHV Telephone Confidence Score: 1 (highest) to 5 (lowest). PHV 1–3 are high confidence. 4 = possible disconnects. 5 = likely disconnects. Integer 1–5
DACode Directory Assistance Flag: Y–Listed, D–Delisted, Blank–Private/Unlisted String
TZ Time Zone numeric: Hawaii=2, Alaska=3, Pacific=4, Mountain=5, Central=6, Eastern=7, Atlantic=8 Integer 2–8
DSO Daylight Savings Observation – whether the line observes DST changes Integer 1 or blank
PrePaid Indicates if the phone number is a prepaid line Y, N, or Blank
knownLitigator Indicates if the consumer is a known litigator. 0 = not a known litigator; 1 = known litigator. Integer 0, 1

Testing

To ensure that all test data remains separate from Production data and is excluded from reporting and analysis, include the test parameter in every test API request.

Test Parameter

&test=1

Example Request

https://api.leadid.com/SingleQuery?lac={ACCOUNTCODE}&lak={AUDITKEY}&lpc={PROVIDERCODE}&data={DATA}&test=1

Example JSON Representation

{
  "endpoint": "https://api.leadid.com/SingleQuery",
  "parameters": {
    "lac": "{ACCOUNTCODE}",
    "lak": "{AUDITKEY}",
    "lpc": "{PROVIDERCODE}",
    "data": "{DATA}",
    "test": 1
  }
}

Important: The test parameter must be included exactly as &test=1. If it is omitted or formatted incorrectly, the submitted data will be written to Production tables.

Validation Process

  1. Execute your API tests using &test=1.
  2. Send the complete API request URL(s) used during testing to: customersupport@infutor.com
  3. Wait for confirmation from the Support Team that testing has been validated.
  4. Do not launch changes into Production until you have received confirmation.

Notes

  • Test traffic is isolated from Production reporting and analytics.
  • Production data contamination can occur if the test parameter is not included exactly as specified.
  • Providing the full request string helps the Support Team verify that test records were correctly processed.

Appendix A: JSON API Example

Example Request

https://api.leadid.com/SingleQuery?lac={ACCOUNTCODE}&data=FullName=randomFullName&FName=FName&LName=LName&Address1=Address1&Address2=Address2&City=City&State=State&Zip=Zip&Phone=Phone&Phone2=Phone2&Email=Email

Example Response

{
  "audit": {
    "ConsumerData": {
      "persistentId": "8B7BE3E01CF0541463E4A93C44A26F45",
      "householdId": "1EC643B8EBAF9E04F1859358F94821E106EA2537E832E0C65818BF281A7CA17951F6708EF462A299BECFD2AC8FA7383C",
      "matchLevel": 1,
      "IDCompletion": {
        "raw_response": {
          "output": [
            {
              "results": [
                {
                  "completion": {
                    "names": [
                      {
                        "firstName": "JESSICA",
                        "lastName": "SAMPLE",
                        "middleName": "R",
                        "busName": "",
                        "suffix": ""
                      }
                    ],
                    "addresses": [
                      {
                        "houseNumber": "456",
                        "predir": "",
                        "streetName": "TEST",
                        "streetType": "AVE",
                        "postdir": "",
                        "aptType": "",
                        "aptNumber": "",
                        "city": "EXAMPLETOWN",
                        "st": "MA",
                        "zip": "01999",
                        "zip4": "1234",
                        "dpc": "999",
                        "crte": "T001",
                        "cnty": "999",
                        "z4type": "S",
                        "dpv": "Y",
                        "deliverable": "Y",
                        "lastSeen": "20251204"
                      }
                    ],
                    "phones": [
                      {
                        "phone": "5552013344",
                        "phoneType": "V",
                        "did": "",
                        "recordType": "R",
                        "firstSeen": "20140205",
                        "lastSeen": "20240907",
                        "telcoName": "TEST TELCO",
                        "matchLevel": "I",
                        "phv": 1,
                        "daCode": "Y",
                        "tz": 7,
                        "dso": 1,
                        "prePaid": "N"
                      }
                    ],
                    "emails": [
                      {
                        "email": "jessica.sample@testdomain.com",
                        "suppressionCode": "N",
                        "urlSources": "TESTSOURCE.COM",
                        "lastSeen": "20240907",
                        "matchLevel": "I"
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Appendix B: API Response Codes

The following is a table of potential output response codes and messages. Returned in the top-level error object when the request cannot be processed.

Code Description
100 Internal Error. Retry – InfutorData side error. Initiate retry logic.
101 Critical Error. An error occurred that may not resolve if retried. Report to administrator.
401 Unauthorized. The Authorization header is missing or the token provided is invalid.
403 Permission Denied. Account is disabled or inactive.
7000 Testing Not Enabled. The account is not configured for test queries.
2000 Account Code Not Set. An account code has not been provided.
2001 Malformed Account Code. The account code provided is malformed or blank.
2002 Invalid Account Code. The account code provided is invalid.
4001 Malformed Audit Key. The audit key provided is malformed or blank.
6000 Invalid Audit Key. The audit key provided is invalid.

Identity-Specific Error Codes

Returned in the audit.market.ConsumerData section when an IDCompletion / Attributes / ID Scoring level error occurs.

Code Description
100 Internal Error. Retry – InfutorData side error. Initiate retry logic.
101 Critical Error. An error occurred that may not resolve if retried. Report to administrator.
1010 Missing or Invalid Data. The data provided was missing or could not be processed.
1040 No Data Available. No results were found for the provided input.

Support

Please reach out to Customer Support for questions or assistance.

Was this article helpful?

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.