API Usage - Old

Introduction

Factori's APIs enable your platform to enhance your customer's profiles with powerful search and enrichment capabilities, providing you with a comprehensive view.

What is a REST API, anyway?

API is short for ‘Application Programming Interface’ . An API is a set of rules that lets programs talk to each other, exposing data and functionality across the Internet in a consistent format.

REST stands for ‘Representational State Transfer’. This is an architectural pattern that describes how distributed systems can expose a consistent interface. When people use the term ‘REST API’, they are generally referring to an API accessed using the HTTP protocol at a predefined set of URLs.

These URLs represent various resources — any information or content accessed at that location, which can be returned as JSON, HTML, audio files, or images. Often resources have one or more methods that can be performed on them over HTTP, like GET, POST, PUT, and DELETE. The action represented by the first and last of these is clear, but POST and PUT have specific meanings. How they are defined is confusing, but the general rule is: use POST to create resources, and PUT to update resources.

Working with Factori’s APIs

API Authentication

To ensure the security and integrity of data, the Factori API requires authentication before making any API requests. The authentication process involves the following steps:

The authentication process involves the following steps:

1. Request Access: Users or brands interested in accessing the Factori API need to submit a request through the "Developers" section on the Factori website. This request initiates the verification process.
2. API Portal Access: Upon verification and contract establishment, the user or brand receives a temporary password, along with a link to the Factori API portal. These credentials provide access to the API and initiate the authentication process.

Factori supports HTTP Bearer authentication.

What is a Bearer Token?

A Bearer token is used for authentication and authorization in web applications and APIs to hold user credentials and indicate authorization for requests and access.

Bearer tokens are generated based on protocols and specifications such as OAuth and JWT (JSON Web Token). The authenticated user obtains the Bearer token issued by the server and sends it to the server in the header of the request. The server verifies the received bearer token and controls user access based on the token. The Bearer token is also usually sent over an encrypted connection via HTTPS. This prevents unauthorized access by malicious third parties even if the token is stolen and allows you to protect the URLs on your web server so that only you can access them.

In order to authenticate with HTTP, you may provide the email ID and password with the following URL format:

curl --location 'https://api.factori.ai/api/user/authenticate' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email":"your-email",
    "password":"your-password"
}'

Once you are successfully authenticated you will receive your Bearer token in the response header. This Bearer token needs to be used to authenticate all subsequent API request to fetch Factori data.

Note: The API token once generated will be valid for 24 hours.

API Usage

• persons_attributes in Factori APIs help you provide filters based on which you will be receiving data of individuals
• output_fields in Factori APIs help you receive only those attributes that are useful to you instead of receiving all attributes in the response. For example, "output_fields": ["first_name", "company_name"] means to say that if a record matches a given criteria return only the first name and the company name
• must_contain in Factori APIs help you in fetching a specific record if and only if a value exists for that key. For example, "must_contain": ["phone_numbers", "emails"] means to say that the API needs to fetch a record only if the record contains values for phone numbers and emails
• maximum_record_limit in Factori APIs help you in specifying the number of credits you would like to utilise in a given request
• All emails in our end are lowercase and empty spaces are trimmed before hashing.
• All phone numbers in our end have their extensions trimmed and don't have any hyphen (-) . Also empty spaces are trimmed before hashing. Our inputs accept phone numbers without extensions, spaces and hyphens.
• All maids in our end are lowercase and empty spaces are trimmed before hashing.
• Factori APIs accept only abbreviations for States as mentioned in - https://about.usps.com/who/profile/history/state-abbreviations.htm
• Factori APIs accept "M" for male and "F" for female as values for gender
• Factori APIs follow standard SIC codes as mentioned in https://www.sec.gov/corpfin/division-of-corporation-finance-standard-industrial-classification-sic-code-list
• Factori APIs follow standard NAICS codes as mentioned in https://www.census.gov/naics/?58967?yearbck=2022
• net_worth field in Factori APIs accept the following ranges for filtering based on an individual's net worth

• household_income field in Factori APIs accept the following ranges

• If the API response for a given request exceeds 100 records then the maximum_record_limit needs to be used to specify the number of records that the user would like to receive
• Each API response can only return a maximum of 10,000 records
• Each record returned will deduct 1 credit
• The API will only return records if and only if you have sufficient credits
• The response fields will depend on the attributes that have been opted for during contract agreement
• For Credit top up please reach out to your Account Growth team

Types

1. Search

The Search API is built to help you search for individuals that satisfy a given criteria and will only return limited number of fields in the response, as mentioned below

2. Enrich

The Enrich API is built to help you enrich your existing data with attributes that provide you with a complete graph of your customer. The general practise is to use the Search API to filter records and then use the Enrich API to enrich only those relevant records

The Enrich API response gives you access to all available attributes mentioned in the page above.

3. Verify

In an increasingly digital world, the incidence of digital fraud is on the rise. Malicious individuals are continuously seeking fresh methods to engage in fraudulent activities, including the creation of synthetic identities, identity theft, and taking over user accounts. Companies are faced with the challenge of maintaining a seamless customer onboarding experience while simultaneously working to reduce fraud and safeguard their platforms.

The API can accept a wide variety of inputs to verify an individual such as:

1. Phone
2. Email
3. MAID

Example

1. An example for a Search Request

curl --location 'https://api.factori.ai/enrich/personDetail' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Token>' \
--data '{
    "persons_attributes": {
        "city": "los angeles",
        "state": "ca",
        "net_worth": "$50000_$99999"
    },
    "must_contain": [
        "first_name",
        "last_name",
        "gender"
    ],
    "output_fields": [
        "first_name",
        "last_name",
        "gender",
        "address"
    ],
    "maximum_record_limit": 100,
    "query_type": "SEARCH"
}'

Rate Limits

To ensure fair usage and maintain system stability, the Factori API enforces rate limits and throttling. Currently, the platform supports up to 200 requests/minute with a 60 second cool off period. It is essential to consider these limits while designing your application and handling high-volume requests.

Error Handling

In cases where an API request encounters an error, the Factori API provides informative error messages and corresponding status codes. The error handling section of the documentation explains the possible error scenarios, their meanings, and recommended approaches for error handling and troubleshooting.

HTTP Error codes

1. 429: HTTP Error 429 is an HTTP response status code that indicates the client application has surpassed its rate limit, or number of requests they can send in a given period of time.
2. 400: HTTP Error 400 Bad Request status code that means that the request you sent to the website server, often something simple like a request to a search request was somehow incorrect or corrupted and the server couldn't understand it.
3. 401: HTTP Error 400 Unauthorized is returned when the authentication provided is invalid. See our Authentication Overview for details on authenticating API requests.
4. 403: HTTP 403 Forbidden is returned when the authentication provided does not have the proper permissions to access the specific URL.
5. 500: HTTP 500 Internal server error is a general error message. It covers unexpected issues that don't fit into existing error codes.