# Create Client Creates a new client. Endpoint: POST /api/v3/clients Version: 3.1.0 Security: apiKeyAuth ## Query parameters: - `api_key` (string, required) Your API Key. Example: "YOUR_API_KEY" ## Request fields (application/json): - `client` (object, required) Client fields accepted on create and update. Any other key inside client is ignored. Sending initial_balance inside client is not supported: the request fails with HTTP 500. Use PUT /api/v3/clients/{id}/initial_balance instead. - `client.name` (string, required) Example: "John Doe" - `client.code` (string) Maximum length is the database default, not an enforced business rule. Example: "12345" - `client.language` (string) Maximum length is the database default, not an enforced business rule. Example: "pt" - `client.email` (string) Example: "john.doe@invoicexpress.com" - `client.address` (string) No enforced character limit (text column). Example: "Avenida da República, Lisboa" - `client.city` (string) Maximum length is the database default, not an enforced business rule. Example: "Lisboa" - `client.postal_code` (string) Maximum length is the database default, not an enforced business rule. Example: "1050-555" - `client.fiscal_id` (string) Maximum length is the database default, not an enforced business rule. Example: "123456789" - `client.website` (string) Example: "www.invoicexpress.com" - `client.country` (string) Maximum length is the database default, not an enforced business rule. Example: "Portugal" - `client.address_country` (string,null) ISO country code of the client's address. Stored as sent (an unknown code is kept as received); send it empty or null to clear it. Omit the key to leave the stored value unchanged. Example: "PT" - `client.phone` (string) Example: "963214569" - `client.phone_country_id` (integer) Example: 1 - `client.mobile` (string) Maximum length is the database default, not an enforced business rule. Example: "999999999" - `client.mobile_country_id` (integer) Example: 1 - `client.fax` (string) Example: "213456789" - `client.preferred_contact` (object) - `client.preferred_contact.name` (string) Contact-level name has no length validation, unlike the client-level name (max 100); the limit shown is the database default. Example: "Bruce Norris" - `client.preferred_contact.email` (string) Contact-level email allows one character more than the client-level email (max 254). Example: "bruce.norris@invoicexpress.com" - `client.preferred_contact.phone` (string) Contact-level phone has no length validation, unlike the client-level phone (max 20); the limit shown is the database default. Example: "213456789" - `client.preferred_contact.mobile` (string,null) Digits only (4-14). Validated against /\A\d{4,14}\z/. - `client.observations` (string,null) No enforced character limit (text column). - `client.send_options` (integer) Example: 1 - `client.payment_days` (integer) - `client.tax_exemption_code` (string) Maximum length is the database default, not an enforced business rule. Example: "M00" - `client.payment_mechanism` (string) Maximum length is the database default, not an enforced business rule. Example: "MB" - `client.currency_id` (integer) Example: 1 ## Response 201 fields (application/json): - `client` (object) Client as returned by show, create, update, archive and unarchive. country is omitted when the client has none. These fields fall back to the account's own value when the client has none of its own: language, observations, send_options, document_copies (same value as send_options), payment_days, tax_exemption_code, payment_mechanism and currency_id. use_account_settings is true when the client has none of these set itself. - `client.id` (integer) Example: 191880320 - `client.name` (string) Example: "John Doe" - `client.code` (string,null) Maximum length is the database default, not an enforced business rule. Example: "JS" - `client.language` (string) Falls back to the account language. Maximum length is the database default, not an enforced business rule. Example: "en" - `client.email` (string,null) Example: "john.doe@invoicexpress.com" - `client.address` (string,null) No enforced character limit (text column). Example: "Avenida da República, Lisboa" - `client.city` (string,null) Maximum length is the database default, not an enforced business rule. Example: "Lisboa" - `client.postal_code` (string,null) Maximum length is the database default, not an enforced business rule. Example: "1050-555" - `client.fiscal_id` (string,null) Maximum length is the database default, not an enforced business rule. Example: "123456789" - `client.website` (string,null) - `client.country` (string) The client's stored country (fiscal country). Omitted when the client has none. Maximum length is the database default, not an enforced business rule. Example: "Portugal" - `client.address_country` (string,null) ISO country code of the address: the stored address country, else the client's country, else the account's tax location, else PT. Example: "PT" - `client.phone` (string,null) - `client.phone_country_id` (integer,null) Example: 1 - `client.mobile` (string,null) Maximum length is the database default, not an enforced business rule. - `client.mobile_country_id` (integer,null) - `client.fax` (string,null) - `client.preferred_contact` (object) Preferred contact info. May be an empty object when no contact is set. - `client.preferred_contact.name` (string,null) Contact-level name has no length validation, unlike the client-level name (max 100); the limit shown is the database default. - `client.preferred_contact.email` (string,null) Contact-level email allows one character more than the client-level email (max 254). - `client.preferred_contact.phone` (string,null) Contact-level phone has no length validation, unlike the client-level phone (max 20); the limit shown is the database default. - `client.preferred_contact.mobile` (string,null) Digits only (4-14). Validated against /\A\d{4,14}\z/. - `client.observations` (string,null) Falls back to the account observations. No enforced character limit (text column). - `client.open_account_link` (string) Example: "http://www.app.invoicexpress.com/suppliers/47888a650591050dfc40e4511fe9da18db165cb4" - `client.document_copies` (integer,null) Same value as send_options (client value, else the account's). - `client.send_options` (integer,null) Falls back to the account value. - `client.payment_days` (integer,null) Falls back to the account value. - `client.tax_exemption_code` (string,null) Falls back to the account value. Maximum length is the database default, not an enforced business rule. - `client.payment_mechanism` (string,null) Falls back to the account value. Maximum length is the database default, not an enforced business rule. - `client.currency_id` (integer) Falls back to the account currency. Example: 1 - `client.use_account_settings` (boolean) Example: true - `client.consumidor_final` (boolean) - `client.can_be_deleted` (boolean) true when the client has no documents other than deleted ones, so DELETE will succeed. Drafts and canceled documents count. A client that cannot be deleted can be archived instead. - `client.archived` (boolean) true when the client is archived. Change it with the archive and unarchive endpoints; it is ignored on create and update. - `client.archived_at` (string,null) When the client was archived, or null when it is not archived. ## Response 401 fields (application/json): - `errors` (array) Example: [{"error":"Authentication Error"}] - `errors.error` (string) ## Response 422 fields (application/json): - `errors` (array) Example: [{"error":"An unexpected error occurred"}] - `errors.error` (string) ## Response 500 fields (application/json): - `errors` (array) Example: [{"error":"An unexpected error occurred"}] - `errors.error` (string)