- Docs
- API reference
- Endpoints and schemas
- KYB API
- Request options
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.
Example
Section titled “Example”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 --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.
Add-on tasks
Section titled “Add-on tasks”An add-on task adds a task to risk_summary.tasks, after the standard tasks.
Each runs only with top_n=1.
watchlistAdds thewatchlisttask andwatchlistsScreens against sanctions, debarment and PEP lists; see Watchlist screening. Needs nothing in the body. With
top_nabove 1, only thewatchlistsarray returns.tin_verificationAdds thetin_verificationtaskChecks with the IRS that the TIN matches the business name; see
tin_verification. Needs a business name (name,namesorprimary_name), andtin(ortinswith 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 thessn_verificationtaskChecks with the IRS that the SSN matches the submitted person’s name; see
ssn_verification. Needsperson.ssnof 9 digits once dashes are removed.
A request that breaks a TIN or SSN requirement, including top_n above 1,
returns 400. See
Validation.
Add-on attributes
Section titled “Add-on attributes”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.
bankruptciesAddsbankruptciesto registered entitiesThe bankruptcy filings for each matched registered entity. To find a brand’s filings, follow its
registered_entity_ids. See Bankruptcies.operating_statusAddsoperating_statusto operating locationsOpen,Closed,Temporarily ClosedorUnknown.Unknownwhen Enigma has no operating status for the location. See Operating locations.phone_numbersAddsphone_numbersto operating locationsAn array of objects, each with one
phone_numberstring. See Operating locations.person_addressesAddsaddressesto registered personsThe 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-levelbackground_taskNegative 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 orfailed; 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.
Card-transaction values
Section titled “Card-transaction values”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_sizeThe average card transaction size, in dollars.
card_transactions_countThe total number of card transactions.
card_revenue_amountThe sum of all card transaction amounts, in dollars.
card_revenue_yoy_growthThe ratio of the period’s card revenue to the same period one year earlier.
card_revenue_prior_period_growthThe ratio of the period’s card revenue to the previous period.
card_customers_average_daily_countThe average number of unique customers per day.
has_transactions1if the brand had any card transactions in the period,0otherwise.refunds_amountThe total amount refunded, in dollars.
Write the attrs list
Section titled “Write the attrs list”- 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=Watchlistruns no screening and returns200. 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 inrisk_summary.tasks. Do not rely on field presence alone to confirm an add-on attribute: its field appears only where a match carries it, andbackground_taskis absent when no registered entity matched (see What the POST returns). - The bare value
card_transactionsreturns400, even alongside other values. Name the card-transaction values you want instead. - On a
person-only screen,
attrsmust be exactlywatchlist.
Attribute-only requests
Section titled “Attribute-only requests”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.
Response shape
Section titled “Response shape”- Matching is unchanged. Enigma reads the same body and applies
top_nandmatch_thresholdas for a package request. - The values are the add-on values, plus registration fields.
productsaccepts every add-on attribute, the three add-on task values, andregistration.<field>(see Registration fields). - The response
dataholds IDs plus your attributes. Each registered entity has itsid. Each brand has itsidandregistered_entity_ids. Your attributes are added with the objects that hold them:- An operating-location attribute adds
operating_locations[], each with itsid. person_addressesor aregistration.<field>addsregistrations[], each with itsaddresses.person_addressesalso addsregistrations[].persons[], each with itsname.
- An operating-location attribute adds
- No standard tasks run. With
top_n=1,risk_summary.tasksis an empty array unless you listwatchlist,tin_verificationorssn_verification, which add their tasks as they do inattrs.
For how this compares with the other options, see How the response changes.
Registration fields
Section titled “Registration fields”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.
Errors
Section titled “Errors”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.
Account enablement
Section titled “Account enablement”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.
Related
Section titled “Related”- Packages: the standard tasks and fields that add-ons build on.
- How checks work: what each add-on task checks, and its results.
- Onboard a business: a package with watchlist screening and a TIN check in one request.
- Screen a person: watchlist screening for a person with no business to match.
- Get attributes only: a complete attribute-only request and response.