Skip to main content

Receive a FINTRX message

POST 

/v1/fintrx

The single URL of FINTRX's External API. FINTRX posts every message as an envelope { "name": "<type>", "payload": { ... } }.

Auth: send the API key raw (Authorization: <key>) or as Authorization: Bearer <key>; both reach the API, as this route has its own gateway route that passes the Bearer form through. Only an API key is accepted: a request authenticated any other way answers 401. The key picks the organization and the user the changes are saved as.

Messages: a firm or a person of any FINTRX record type, named send_<record type>_entity_to_ext_api or send_<record type>_contact_to_ext_api and carrying the record under payload.<record type>_entity or payload.<record type>_contact: ria (RIA), bd (broker-dealer), fo (family office) or any other. Every record type is written by the same rules and the same field paths.

  • A firm message, such as send_ria_entity_to_ext_api with payload.ria_entity or send_fo_entity_to_ext_api with payload.fo_entity, writes the firm onto the one Investor holding the firm's FINTRX id for its record type, else the one whose website host matches team_page (the id is then stored on it), into the fields mapped to FINTRX. An Investor that matches gets its mapped custom fields only: its name, website and other built-in fields are left as they are. When no Investor matches, one is created, even in an organization that maps no field to FINTRX, from the firm's name, website, location, employee count, founding year and description and then its mapped fields, and the FINTRX id is stored on it; it is not enriched. Outcomes: written, unchanged, no_mapped_fields (no field is mapped to FINTRX, and the Investor matched or creating one failed), no_match (no Investor matched and creating one failed: nothing was created), created (an Investor was created), no_name (no Investor matched and the firm has no name: nothing was created), no_website (no Investor matched, and either the firm has neither a FINTRX id nor a usable team_page, so a later message could not find it again, or creating one failed: nothing was created), ambiguous (several Investors hold the id, or share the host: nothing was written or created).
  • A contact message, such as send_ria_contact_to_ext_api with payload.ria_contact or send_fo_contact_to_ext_api with payload.fo_contact, writes the person onto the one Contact holding the person's FINTRX id for its record type, else the one that holds any of their FINTRX addresses in any of its email fields (the id is then stored on it), into the fields mapped to FINTRX. Every top-level field whose key contains email, in any casing (email, secondary_email, personal_email), is read as an address. A Contact that is found gets its mapped custom fields only. When no Contact holds the person, one is created in the organization's default list, which needs an owner, from the person's name, job title, up to three email addresses and three phone numbers, location and LinkedIn profile, with the firm's name and website as their job, and then the mapped fields, and the FINTRX id is stored on it (never enriched). Outcomes: written, unchanged, no_mapped_fields, created (a Contact was created), no_email (no valid email and no FINTRX id: nothing was created), no_default_list (the organization has no default list, or its default list has no owner: nothing was created), no_name (the person has neither a name nor a valid email: nothing was created), no_match (the matched Contact is gone, or the key's user cannot edit it), ambiguous (several Contacts hold the id, or an address, so nothing is written or created and, for the id, the addresses are not tried), no_contact_payload (payload has no object under the message's contact key).
  • FINTRX sends a person's firm as a firm message alongside the person's contact message, so a contact sync creates the firm's Investor, when none matches, as well as the Contact.
  • Any other name, such as the news, notes, tags, tasks and token refresh messages, is acknowledged and ignored (ignored).

Scopes: a key with stored scopes needs investors:write for every message, and contacts:write as well for a contact message, which also needs the Contacts module on. A key with no stored scopes is limited only by its read-only flag, and a read-only key is refused.

The response is 200 whatever the outcome (one of the outcome values) once the message is accepted, except that a Contact or Investor create that times out waiting for the record lock answers 409 so FINTRX retries it, as FINTRX treats any other status as a failed request, and a 401 as an expired token. Any other create error is logged and answers 200 with the outcome the message gets without creation (no_match, no_email, no_website or no_mapped_fields), and FINTRX does not retry it; a create that fails after saving the record leaves it without its FINTRX id. A message the CRM cannot accept answers 400 (not an envelope), 401 (not an API key), 403 (the Investors module is disabled, or the key lacks a scope or is read-only) or 404 (the organization has not enabled the FINTRX integration).

Request​

Responses​

Message received