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_apiwithpayload.ria_entityorsend_fo_entity_to_ext_apiwithpayload.fo_entity, writes the firm onto the one Investor holding the firm's FINTRXidfor its record type, else the one whose website host matchesteam_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 FINTRXidis 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 FINTRXidnor a usableteam_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_apiwithpayload.ria_contactorsend_fo_contact_to_ext_apiwithpayload.fo_contact, writes the person onto the one Contact holding the person's FINTRXidfor 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 containsemail, 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(payloadhas 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
- 200
- 400
- 401
- 403
- 404
- 409
- 500
Message received
Body is not an envelope with a string name and an object payload, or a firm message has no object under its entity key (payload.<record type>_entity)
Invalid or missing API key
The organization has disabled the Investors module, or the API key is read-only, or lacks investors:write, or, on a contact message, lacks contacts:write (a scoped key) or the organization has disabled the Contacts module
FINTRX integration not enabled for the organization
A Contact or Investor create timed out waiting for the record lock (code: FINTRX_RECORD_LOCK_TIMEOUT); FINTRX retries it
Writing the firm or contact failed. A firm or contact the CRM rejects for its data (a URL outside the organization's allowed domains, say) comes back with that error's 4xx status instead