Pibisi API documentation version v2
https://api.pibisi.com/v2
Introduction
This document describes the elegant, easy-to-use REST API to communicate with Pibisi.
Integration step by step
HELLO WORLD!
- First of all you will need to have a valid credential i.e. a JWT, which you can request at integrations@pibisi.com
- Check that everything is working calling [GET]/v2/users/me.
- Get your account UUID (or account UUIDs) using the endpoint [GET]/v2/users/me/accounts.
Once you have valid credentials and everything is running let's deep into the main workflows.
MONITORING CUSTOMERS
- Add a new customer to be managed by Pibisi using the endpoint [POST]/v2/accounts/{account}/customers and expect in the response a unique identifier (UUID) for this customer that you should store in your database.
- Repeat the step 1 with every customer in your database.
- (Optional webhook) Provide the team of Pibisi with your custom endpoint which we should call back when a new relevant piece of information is gathered about any of your customers managed by Pibisi.
- Call alternatively the endpoint [GET]/v2/accounts/{account}/customers/{customer} to get updated information about any of your customers.
RESEARCHING PERSONS
- Make a new query using the endpoint [POST]/v2/accounts/{account}/subjects/find and expect in the response an list of possible matches ordered by similarity for the given input.
- You can retrieve full information about every single match using their unique identifier (UUID) with [GET]/v2/accounts/{account}/subjects/{subject}
- If the search did not return any matches, or none of them is a valid match, you can retrieve a negative report using the endpoint [POST]/v2/accounts/{account}/subjects/report.
And that's it, you are now fully integrated with Pibisi!
Data types
In the following sections you can find a detailed explanation of the main data types.
POI (PIECE OF INFORMATION)
Every POI has the following structure:
- type (string). Type of information.
- content (string | object). The actual piece of information. Depending on the data type the content will have the form of a string or of an object containing fields. Further nesting levels are not allowed.
Main POI types and content fields (alphabetic order(:
birth.date.
- Description: Birth or foundation date.
- Content: (string YYYY-MM-DD)
- Examples:
- {"type":"birth.date","content":"2019-03-15"}
- {"type":"birth.date","content":"2000-01-01"}
birth.place
- Description: Birth place
- Content: (object) Fields:
- city (string). (Opt.) City
- country (string ISO 3166-1 alfa-3). (Opt.) Country.
- Examples:
- {"type":"birth.place","content":{"country":"ESP","city":"Málaga"}}
- {"type":"birth.place","content":{"country":"PRT","city":"Porto"}}
gender
- Description: Gender
- Content: (char) One of the following:
- M. Male
- F. Female
- N. Not informed
- Examples:
- {"type":"gender","content":"F"}
- {"type":"gender","content":"M"}
function
- Description: Charge in a private organization (other than a political party).
- Content: (object). Fields:
- charge (string). Denomination of the private charge.
- organization (string). Organization or company holding the private charge.
- from (string YYYY-MM-DD). Date accessing the private charge.
- to (string YYYY-MM-DD). Date leaving the private charge.
- Examples:
- {"type":"function","content":{"charge":"CEO","organization":"Apple Inc."}}
- {"type":"function","content":{"charge":"Administrator","organization":"Procera Technologia S.L.","from":"2018-03-15","to":"2025-03-15"}}
function.political
- Description: Charge in a political entity or party.
- Content: (object). Fields:
- charge (string). Denomination of the charge.
- organization (string). Political party or entity.
- from (string YYYY-MM-DD). Date accessing the charge.
- to (string YYYY-MM-DD). Date leaving the charge.
- Examples:
- {"type":"function.political","content":{"charge":"General Secretary","organization":"The People's Front of Judea"}}
- {"type":"function.political","content":{"charge":"Supervisor","organization":"Judean People's Front","from":"2018-03-15","to":"2025-03-15"}}
function.public
- Description: Charge in a public organization.
- Content: (object). Fields:
- charge (string). Denomination of the public charge.
- organization (string). Organization holding the public charge.
- scope (string). Scope (typically the jurisdiction) of the public charge.
- country (string ISO 3166-1 alfa-3). Country.
- from (string YYYY-MM-DD). Date accessing the public charge.
- to (string YYYY-MM-DD). Date leaving the public charge.
- Examples:
- {"type":"function.public","content":{"country":"ESP","charge":"Ministry","organization":"Foreign Affairs Ministry"}}
- {"type":"function.public","content":{"country":"BRA","charge":"Vereador","organization":"Nova Monte Verde-MT","from":"2021-01-01","to":"2025-01-01"}}
id.driving_license
- Description: Driving license identification.
- Content: See id.national
- Examples: See id.national
id.internal
- Description: Internal identifier inside a customer company account.
- Content: See id.national
- Examples: See id.national
id.national (object). National id. Fields:
- Description: National identification (different than passport).
- Content: (object) Fields:
- country (string ISO 3166-1 alfa-3). Country issuing the document number.
- number (string). Passport ID number.
- expiration_date (string YYYY-MM-DD). Expiration date of the current document.
- Examples:
- {"type":"id.national","content":{"country":"ESP","number":"123456789A","expiration_date":"2030-06-12"}}
- {"type":"id.national","content":{"country":"PRT","number":"123456789"}}
id.passport
- Description: Passport identification.
- Content: See id.national
- Examples: See id.national
media
- Description: Adverse media.
- Content: (object). Fields:
- action (string). One of the following:
- absolved
- arrested
- blacklisted
- convicted
- investigated
- indicted
- released
- wanted
- issue (string). Charges or topics. One of the following:
- arms_trafficking
- corruption
- drug_trafficking
- embezzlement
- extortion
- fraud
- money_laundering
- organized_crime
- pbc_violation
- sex_trafficking
- tax_evasion
- terrorism
- issuer (string). Institution issuing the adverse information.
- from (string YYYY-MM-DD). Publishing date.
- url (string). Public url to the media content.
- action (string). One of the following:
- Examples:
- {"type":"media","content":{"action":"absolved","issue":"corruption","issuer":"BBC news","url":"https:/ /bbc.com/article/12345678"}}
- {"type":"media","content":{"action":"investigated","issue":"money_laundering","issuer":"El País","url":"https:/ /elpais.com/article/12345678"}}
name.full
- Description: Full name, including first name, second name and surname.
- Content: (string)
- Examples:
- {"type":"name.full","content":"Walt Disney"}
- {"type":"name.full","content":"The Coca-Cola Company"}
nationality
- Description: Nationality.
- Content: (string ISO 3166-1 alfa-3)
- Examples:
- {"type":"nationality","content":"ESP"}
- {"type":"nationality","content":"COL"}
person
- Description: Type of person or entity.
- Content: (char) One of the following:
- P. Natural person
- E. Legal person
- D. Domain
- Examples:
- {"type":"person","content":"P"}
- {"type":"person","content":"E"}
sanction
- Description: International sanction.
- Content: (object). Fields:
- types (collection). Sanction types. Can be several of:
- ARE (Arms embargo),
- FOA (Assets freeze),
- TRB (Travel ban),
- IBC (Ineligible to become a Bank Counterparty),
- EPD (Export privileges denial),
- EAR (Export administrations regulation),
- FMT (Forbid military assets trade),
- FFT (Forbid financial assets trade),
- FDT (Forbid dual use assets trade),
- FPT (Forbid prospecting assets trade),
- MFA (Making funds available),
- EPP (Exclusion from a public procurement available),
- SOP (Suspension of payments),
- SVE (Prohibition to offer services in maritime and air vessels)
- reason (text). Reason for getting sanctioned.
- issuer (string). Institution issuing the sanction.
- scope (string). Scope (tipically the jurisdiction) of the public charge.
- country (string ISO 3166-1 alfa-3). Country.
- from (string YYYY-MM-DD). Date when the sanction started.
- to (string YYYY-MM-DD). Date when the sanction finished.
- types (collection). Sanction types. Can be several of:
- Examples:
- {"type":"sanction","content":{"issuer":"OFAC","types":"FFT,ARE","reason":"Actual reason"}}
- {"type":"sanction","content":{"issuer":"UN","types":"FOA","reason":"Actual reason","from":"2021-01-01","to":"2025-01-01"}}
ALERTS
Alert properties:
- status (string). Status. One of the following:
- pending. The alert is pending to be resolved.
- monitored. The alert is being attended but not yet resolved.
- accepted. The information of the alert has been accepted (common case).
- rejected. The information of the alert has been rejected.
- type (string). Type. One of the following:
- has_matches. The customer has one or multiple coincidences.
- is_pep. The customer is a politically exposed person.
- was_pep. The customer was a politically exposed person.
- is_sanctioned. The customer has an international sanction.
- is_terrorist. The customer is a terrorist.
- is_high_risk. The customer belongs to a jurisdiction of risk.
- has_media. The customer has adverse media.
- info_id_expired. The identification document has expired.
- info_id_expired_notice. The identification document is about to expire.
- registered_at (date). The date when the alert was generated.
- processed_at (date). The date when the alert was resolved.
- comment (text). General purpose textual information.
- uuid (UUID). Unique identifier of the alert.
- customer_uuid (UUID). Unique identifier of the related customer within Pibisi.
CUSTOMERS
Object properties:
- status (string). Status. One of the following:
- active. The customer is being monitored.
- inactive. The customer is not being monitored, but the data is accessible.
- deleted. The customer was deleted and the information destroyed.
- risk (string). Risk. One of the following:
- low
- medium
- high
- scoring (object). Scoring information. Fields:
- value: Numeric value representing the risk. 0 if all the 'flags' are inactive. Otherwise 10.
- flags: Customer's risk classification. Fields:
- is_pep. TRUE if the person is PEP. Otherwise FALSE.
- was_pep. TRUE if the person was PEP. Otherwise FALSE,
- was_pep_date. If 'was_pep' is TRUE, the date of the last public charge.
- is_sanctioned. TRUE if the person has an international sanction. Otherwise FALSE.
- was_sanctioned. TRUE if the person had an international sanction. Otherwise FALSE.
- was_sanctioned_date. If 'was_sanctioned' is TRUE, the date of the last public charge.
- is_terrorist. TRUE if the person is a terrorist. Otherwise FALSE.
- has_media. TRUE if the person has adverse media. Otherwise FALSE.,
- has_adverse_info. TRUE if the person has adverse private information. Otherwise FALSE.
- is_high_risk. TRUE if the person belongs to a jurisdiction of risk. Otherwise FALSE.
- has_matches. TRUE if the person has similarities with persons of risk that might be your customer. Otherwise FALSE.
- info: Indicates which POIs relate with the corresponding flag. Fields:
- pep. POIs affecting the PEP flags.
- sanctioned. POIs affecting the sanctioned flags.
- terrorist. POIs affecting the terrorist flag.
- media. POIs affecting the media flag.
- adverse_info. POIs affecting the adverse info flag.
- high_risk. POIs affecting the high risk flag.
- matches. Subjects your customer has similarities with or even might be him/her.
CUSTOMER MATCHES
Object properties:
- status (string). Status. One of the following:
- pending. The match is awaiting to be resolved.
- accepted. The match was accepted as a coincidence by the user.
- rejected. The match was rejected as a coincidence by the user.
- discarded. The match was discarded as a coincidence by the system based on one or several incompatibilities, such as different birth dates.
- similarity (float). Similarity. Similarity percentage between the customer's name and the match's name as a result of the system's comparison algorithm.
- cardinality (float). Cardinality. Float value that indicates how much information was compared equal or almost equal between the customer and the matched subject. The smaller the value the greater the amount of information matched.
- vector (array). Vector. Summary comparison vector indexed by data type group.
Error responses
All API error responses use one of the two following JSON structures:
// Structure 1{ "error": { "code": [status code], "message": [error message], "errors": [errors list] } }// Structure 2 (to be deprecated){ "code": [status code], "message": [error message], }
Description of the response:
[status code]. It is the HTTP status code of the response:
- 400: Bad parameters. The user has provided a bad input.
- 403: Forbidden. The user doesn't have enough privileges to access this resource / endpoint.
- 404: Resource not found. The attempted resource (endpoint) does not exist.
- 405: Incorrect method. The attempted resource / endpoint exists, but the method is not allowed.
- 500: Internal error. It can have multiple causes. You should contact integrations@pibisi.com providing specific information on the error.
[error message]. Human readable further explanation in English language of the specific error. Examples:
- Invalid credentials.
- Credentials expired.
- Invalid POI.
- Invalid POI format.
- ...
[errors list]. In case the execution returns multiple errors they will be listed in this structure with the same format as an [error message].
Endpoints
In the following sections you can find a detailed explanation of all endpoints. Enjoy!
/accounts/{account}/alerts
Rejects and finishes the alert.
You reject an alert when it was based on a wrong person matching. When this occurs, our team will review a request to resolve this wrong match. Until then the person information will still appear merged.
/accounts/{account}/customers
Lists all added customers for the given company account
Registers a new person (customer) to follow up.
You can send multiple pieces of information (aka. pois), but at least the types 'person' (allowed values: 'P' for natural person, and 'E' for legal person) and 'name.full' must be included.
Following pieces of information are mandatory: person, name.full, id.national, birth.date, etc
Make a search in customers.
The search term will be matched against names and document ids of the customers.
Returns all information (visible for the given company account) of a customer
Reactivates a customer after having being deactivated and starts monitoring again.
Returns all alerts related to a given customer
Sets a new risk value
You can change the risk and add a comment. As response you will get the whole customer object.
Deactivates a customer and stops monitoring.
You normally deactivate a customer when he/she is no longer your customer but want or need to keep the data.
Deletes a customer. This operation is destructive and cannot be undone.
You normally delete a customer if the information was erroneous or when you want to eliminate the data for GDPR purposes.
Returns all uploaded documents related to a given customer
Returns all current possible matches for the current customer
Rejects all pending matches for the given customer.
Accepts the given match, meaning it is the same as the customer.
Rejects the given match, meaning it is a false positive.
Adds a new Point of Information to the customer
Returns a PDF document describing a report for the given customer.
/accounts/{account}/services
Scans a set of image files from a single document and returns the read info.
You can upload the front and rear images separately, but it is recommended to upload both using the same request to improve performance.
/accounts/{account}/search-results
Returns all information (visible for the given company account) of a specific search.
Clears all sensitive data of a given search and set the status to 'cleared'.
Returns a PDF document describing a negative search report (no matches found) for a given query.
/accounts/{account}/subjects
Makes a query to find possible matches.
You can query by multiple pieces of information (aka. pois), such as name.full or id.national.
Makes a query to find possible matches only against sanctions and terrorists lists.
You can query by multiple pieces of information (aka. pois), such as name.full or id.national.
Returns all information (visible for the given company account) of a generic subject
Returns a PDF document describing a report for a given subject