Skip to content
Console(opens in a new tab)

Add-ons

Add watchlist screening, TIN and SSN checks, and extra attributes on top of a package, or request attributes without one.

An add-on is a task or an attribute that you request on top of a package with the attrs query parameter on POST /v2/kyb/. An add-on task adds a task to risk_summary.tasks; an add-on attribute adds data to the response. Add-ons work with both packages, and each one must be enabled for your account; see Account enablement.

To return only the attributes you name, with no package and no standard tasks, list them in products instead; see Attribute-only requests.

This request runs verify, adds TIN verification and returns bankruptcy filings. It leaves top_n at its default of 1, which TIN verification requires.

cURL
curl --request POST "https://api.enigma.com/v2/kyb/?package=verify&attrs=tin_verification,bankruptcies" \
--header "x-api-key: $ENIGMA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Enigma Technologies",
"website": "https://enigma.com",
"address": {
"street_address1": "245 5th Ave",
"city": "New York",
"state": "NY",
"postal_code": "10016"
},
"tin": "123456789"
}'

The response has the seven standard tasks of verify, followed by tin_verification, and a bankruptcies array on each registered entity.

An add-on task adds a task to risk_summary.tasks, after the standard tasks. Each runs only with top_n=1.

watchlistAdds the watchlist task and watchlists

Screens against sanctions, debarment and PEP lists; see Watchlist screening. Needs nothing in the body. With top_n above 1, only the watchlists array returns.

tin_verificationAdds the tin_verification task

Checks with the IRS that the TIN matches the business name; see tin_verification. Needs a business name (name, names or primary_name), and tin (or tins with 1 or 2 values) of 9 digits once dashes are removed. Each name is checked against each TIN; see Name and TIN pairs.

ssn_verificationAdds the ssn_verification task

Checks with the IRS that the SSN matches the submitted person’s name; see ssn_verification. Needs person.ssn of 9 digits once dashes are removed.

A request that breaks a TIN or SSN requirement, including top_n above 1, returns 400. See Validation.

An add-on attribute adds data to the response and adds no task. Most add fields to the matched registered entities, brands or operating locations; negative_news adds the top-level background_task.

bankruptciesAdds bankruptcies to registered entities

The bankruptcy filings for each matched registered entity. To find a brand’s filings, follow its registered_entity_ids. See Bankruptcies.

operating_statusAdds operating_status to operating locations

Open, Closed, Temporarily Closed or Unknown. Unknown when Enigma has no operating status for the location. See Operating locations.

phone_numbersAdds phone_numbers to operating locations

An array of objects, each with one phone_number string. See Operating locations.

person_addressesAdds addresses to registered persons

The addresses linked to each person on a registration. Empty for a registered person that is an organization. Once requested, these addresses also count toward address_verification. See Registered persons.

negative_newsAdds the top-level background_task

Negative news about each matched registered entity. Results that are ready come in the response; poll GET /v2/kyb/{task_id} for the rest. The key can be absent or failed; see What the POST returns.

The eight card-transaction values are add-on attributes too. Each adds a key to card_transactions on each matched brand.

Request any of these eight values in attrs or products. Each one adds a key of the same name to brands[].card_transactions, holding an array with one object per period. See Card transactions for the period object, and Card-transaction values for what projected_quantity means under each key.

Show the 8 values
avg_transaction_size

The average card transaction size, in dollars.

card_transactions_count

The total number of card transactions.

card_revenue_amount

The sum of all card transaction amounts, in dollars.

card_revenue_yoy_growth

The ratio of the period’s card revenue to the same period one year earlier.

card_revenue_prior_period_growth

The ratio of the period’s card revenue to the previous period.

card_customers_average_daily_count

The average number of unique customers per day.

has_transactions

1 if the brand had any card transactions in the period, 0 otherwise.

refunds_amount

The total amount refunded, in dollars.

  • List values separated by commas: attrs=watchlist,bankruptcies. One list can mix add-on tasks and add-on attributes.
  • Values are case-sensitive. Spaces around a value are trimmed.
  • An unrecognized value is ignored without an error: attrs=Watchlist runs no screening and returns 200. Check your values against the lists on this page before you send them. After each call, check that every add-on task you asked for appears in risk_summary.tasks. Do not rely on field presence alone to confirm an add-on attribute: its field appears only where a match carries it, and background_task is absent when no registered entity matched (see What the POST returns).
  • The bare value card_transactions returns 400, even alongside other values. Name the card-transaction values you want instead.
  • On a person-only screen, attrs must be exactly watchlist.

An attribute-only request sets the products query parameter instead of package. Enigma matches the business as usual and returns the id of each match plus the attributes you name. Use it for enrichment when you do not need a package’s data or standard tasks. Get attributes only has a complete request and response.

  • Matching is unchanged. Enigma reads the same body and applies top_n and match_threshold as for a package request.
  • The values are the add-on values, plus registration fields. products accepts every add-on attribute, the three add-on task values, and registration.<field> (see Registration fields).
  • The response data holds IDs plus your attributes. Each registered entity has its id. Each brand has its id and registered_entity_ids. Your attributes are added with the objects that hold them:
    • An operating-location attribute adds operating_locations[], each with its id.
    • person_addresses or a registration.<field> adds registrations[], each with its addresses.
    • person_addresses also adds registrations[].persons[], each with its name.
  • No standard tasks run. With top_n=1, risk_summary.tasks is an empty array unless you list watchlist, tin_verification or ssn_verification, which add their tasks as they do in attrs.

For how this compares with the other options, see How the response changes.

Request a registration field as registration.<field>, for example registration.status, one value per field:

Field Returned by identify
registration_state Yes
issue_date Yes
file_number Yes
registered_name Yes
jurisdiction_type No
home_jurisdiction_state No
status No
sub_status No
status_detail No

A misspelled registration field is not rejected. An unknown field after registration. returns no value and no error, so check the field name against this table.

Each of these returns 400 on a products request. Unlike attrs, products rejects a value it does not recognize.

Request Fix
products and package both set Send one or the other. The two are mutually exclusive.
products and attrs both set List every attribute in products. An empty attrs is allowed.
products with no values List at least one value.
An unrecognized value Use only the values above. An unknown registration.<field> name is the exception (see Registration fields).
Bare card_transactions Name the card-transaction values instead.
verification_tier Remove it. The verification tier runs only on verify.
TIN or SSN task with top_n above 1 Set top_n=1. Both tasks require it, in attrs as well.

For the error body, see Errors and rate limits.

To enable an add-on for your account, contact Enigma. Before you go live, confirm with Enigma which add-ons your account includes, and request only those.