--- title: "Invite a Company" method: POST path: "/v1/companies/{company_id}/invite" tags: ["Companies"] --- # Invite a Company `POST /v1/companies/{company_id}/invite` After creating a company, you may invite the company to use Routable's vendor onboarding flow to add additional contact information and payment method details to their vendor profile. This can be done in two ways: via email and/or via an embedded link. To send the invitation via email, set the `send_invite_email` parameter to `true`. The recipients of the email will be based on the `Company's` `Contacts` and their `default_contact_for_company_management` value: - When `actionable`, the contact will receive an email with a clickable link that allows them to submit information. - When `read_only`, the contact will only be notified of the invitation. - When `none`, the contact will not receive an email notification. To use the embedded link flow, use the `get_links` parameter with a value of `true`. You may also specify a `confirmation_redirect_url` to route the user to after completion of the Routable onboarding flow. After inviting a company, their `status` will change to `invited`. After the contact enters their information, the company's `status` will change to `accepted`. Attempting to send an invitation to a Company that is already `accepted` will generate a `400 Bad Request` error. For more information, see our [help docs](https://docs.routable.com/en/articles/3482971-what-does-a-vendor-invite-look-like). ## Path parameters - `company_id` string, uuid, required ## Request body - CompaniesInviteCompanyAction — Invites the `actionable` `Contacts` at the `Company` to add their `PaymentMethods` and `TaxForms` via Routable's hosted vendor onboarding workflow. To perform this action, your `Company` must have at least one `actionable` `Contact`. If you indicate that you want invitation emails to be sent (`send_invite_email = true`), at least one `actionable` `Contact` must also have a valid `email` address. - `acting_team_member` string, uuid, required — The ID of the `TeamMember` performing this action. This will be displayed in the Routable Dashboard and also used as the sender of any invitation emails sent to your `Company`'s `actionable` `Contacts`. - `confirmation_redirect_url` string, uri — A URL on your site that users will be redirected to after completing the onboarding external flow. For use with `get_links: true`. - `get_links` boolean — If `true`, links to an embeddable onboarding flow will be returned in the response. These links contain JWT authentication tokens for each `actionable` `Contact` on the `Company`. Exactly **one** of `get_links` or `send_invite_email` must be `true`. - `message` string — A custom message to include in the invitation email, if `send_invite_email` is `true`. A limited subset of [HTML tags](https://developers.routable.com/docs/html-messages) are permitted for formatting. - `send_invite_email` boolean — If `true`, invitation links will be sent via email to all `actionable` `Contacts` belonging to this `Company`. Exactly **one** of `get_links` or `send_invite_email` must be `true`. ## Response `200` OK - CompaniesCompany - `object` 'Company', required — The object’s type (`Company`). - `id` string, uuid, required — The Company ID. - `business_name` string, required — The Company's business name for banking and tax purposes. - `collect_tax_form` boolean — Defaults to `true` if you use tax collection in your Routable workspace, `false` otherwise. - `contacts` ContactsContactList - `object` 'List', required — The object’s type (`List`). - `links` SharedListLinks, required — Related links. - `self` string, uri-reference, required — Link to this object. - `next` string, uri, nullable — Link to the next page of results. - `prev` string, uri, nullable — Link to the previous page of results. - `results` ContactsContact[], required - `object` 'Contact', required — The object’s type (`Contact`). - `id` string, uuid, required — The Contact ID. - `default_contact_for_company_management` 'actionable' | 'read_only' | 'none' | '' | 'self_managed', required — This field controls how both the Routable dashboard and API will autofill contacts for emails related to company management such as inviting a company to submit their payment information. - When set to `actionable`, the contact will be able to take action on emails related to company management. - When set to `read_only`, the contact will only receive emails related to company management. - When set to `none`, the contact will not receive emails related to company management. - `default_contact_for_payable_and_receivable` 'actionable' | 'read_only' | 'none' | '' | 'self_managed', required — This field controls how both the Routable dashboard and API will autofill contacts for emails related to payables and receivables. - When set to `actionable`, the contact will be able to take action on emails related to payables and receivables. - When set to `read_only`, the contact will only receive emails related to payables and receivables. - When set to `none`, the contact will not receive emails related to payables and receivables. - `email` string, email, nullable — The email for this contact. - `first_name` string — The first name of this contact. - `is_archived` boolean, required — Whether the contact is archived. - `last_email_delivery_problem` 'auto_responder' | 'hard_bounce' | 'refused' | 'soft_bounce' | 'spam_complaint' | 'spam_notification' | 'transient' | 'unknown', nullable — Describes an error that was encountered the last time an email was sent to this Contact via the Routable application. If the last email had no errors, this value will be `null`. | Value | Description | | ----------------- | -----------------------------------| | auto_responder | Automatic email responder (ex: "Out of Office" or "On Vacation"). | | hard_bounce | The server was unable to deliver your message (ex: unknown user, mailbox not found). | | refused | Email service has asked that the address not be used. Which could be because it is not a valid email address, or the recipient has requested an address change. | | soft_bounce | Temporarily unable to deliver the message (i.e. mailbox full, account disabled, exceeds quota, out of disk space). | | spam_complaint | The subscriber explicitly marked this message as spam. | | spam_notification | The message was delivered, but was either blocked by the user, or classified as spam, bulk mail, or had rejected content. | | transient | The server temporarily could not deliver your message (ex: Message is delayed due to network troubles). This may be re-tried and eventually resolve or become a different error.| | unknown | An unknown error occurred when sending the previous email. | - `last_name` string — The last name of this contact. - `phone_number` string, required — An E.164-formatted telephone number. - `phone_number_country` 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'XK' | 'XX' | 'WF' | 'WS' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW', required — Country code in ISO 3166-1 Alpha-2 format. - `links` ContactsContactLinks, required — Related links. - `company` string, uri-reference, required — Link to this Contact's Company. - `invitation_url` string, uri — The URL for Company onboarding, generated by a call to the `Invite a Company` endpoint. - `self` string, uri-reference, required — Link to this object. - `country_code` 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BW' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CV' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IQ' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MX' | 'MW' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RW' | 'SA' | 'SB' | 'SC' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'ST' | 'SV' | 'SX' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VI' | 'VN' | 'VU' | 'XK' | 'WF' | 'WS' | 'XX' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' — Country code in ISO 3166-1 Alpha-2 format. - `created_at` string, date-time, required — The date the Company was created. - `display_name` string, required — The Company's name for display in the Routable Dashboard. - `external_id` string, nullable, required — A unique ID from your system to identify this Company. - `is_archived` boolean — Whether this Company has been archived. - `is_customer` boolean, required — Whether this Company is a customer. - `is_vendor` boolean, required — Whether this Company is a vendor. - `ledger` CompaniesCompanyLedgerMeta, required — Stores this Company's metadata relating it to your accounting software. - `customer_id` string, nullable — The unique ID for this customer in your accounting software. - `vendor_id` string, nullable — The unique ID for this vendor in your accounting software. - `registered_address` union - CompaniesRegisteredAddress, nullable - `address_line_1` string, required — The address' first line. - `address_line_2` string, nullable — The address' second line. - `city` string, required — The address' city. - `country` 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BW' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CV' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IQ' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MX' | 'MW' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RW' | 'SA' | 'SB' | 'SC' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'ST' | 'SV' | 'SX' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VI' | 'VN' | 'VU' | 'XK' | 'WF' | 'WS' | 'XX' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW', required — Country code in ISO 3166-1 Alpha-2 format. - `postal_code` string, required — The address' postal code. - `state` string — The address' state, province or territory. - `object` 'Address', required — The object’s type (`Address`). - `id` string, uuid, required — The Registered Address ID. - object, nullable - `risk_summary` 'cant_validate' | 'dismissed' | 'not_evaluated' | 'outdated' | 'passed' | 'queued' | 'review_required' — Compliance Check status for a `Company`: - `cant_validate`: An error happened and the verification couldn't be finished. - `dismissed`: There were issues found (`review_required`), but they were dismissed by a team member. - `not_evaluated`: Not enrolled for risk monitoring. - `outdated`: When legal data changes outside of the tax flows. - `passed`: Risk checks are all clear. - `queued`: Company was queued for enrollment in risk monitoring. - `review_required`: Identified issues for the entity - Watchlist hits or a TIN mismatch. - `status` 'accepted' | 'added' | 'invited', required — The status of the Company's onboarding. - When set to `added`, this indicates that you have added the Company to Routable. This will be the starting status. - When set to `invited`, this indicates that you have also sent this Company an invitation to submit their business and banking information with Routable. - When set to `accepted`, this indicates that the Company has accepted your invitation and submitted their business and banking information with Routable. - `tax_form_status` 'archived' | 'completed' | 'expired' | 'none', required — Current status of company's tax form. - `tax_form_type` 'w9' | 'w8ben' | 'w8ben_e', nullable — Type of the tax form that the vendor can submit. - `type` 'business' | 'personal', required — The type of Company. - `links` CompaniesCompanyLinks, required — Related links. - `self` string, uri-reference, required — Link to this object. - `compliance_checks` string, uri-reference, required — Link to this Company's Compliance Reports. - `contacts` string, uri-reference, required — Link to this Company's Contacts. - `payables` string, uri-reference, required — Link to this Company's Payables. - `payment_methods` string, uri-reference, required — Link to this Company's Payment Methods. - `receivables` string, uri-reference, required — Link to this Company's Receivables. - `tax_forms` string, uri-reference, required — Link to this Company's most recent TaxForm. ## Other responses - `400` — Thrown when the Company is already in the `accepted` state. --- [API](https://skmtc.net/routable/apis/routable-api.md) · [All operations](https://skmtc.net/routable/apis/routable-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/routable/routable-api/revisions/9f17a8bc982a/schema)