# MakeLeaps API Documentation - Client Section ## Navigation - [Back to index](/api/llms.txt) - [Current section](/api/llms/client.md) ## Topics in this Section - Client Organizations - Client Sending Settings - Contacts ## Client Organizations ### Endpoints - `/api/partner//client/` - Name: Client List - Methods: GET, POST, OPTIONS - `/api/partner//client//` - Name: Client Instance - Methods: GET, PUT, PATCH, DELETE, OPTIONS - `/api/partner//client//contact/` - Name: Client Contact List - Methods: GET, OPTIONS - `/api/partner//client//settings/` - Name: Client Sending Settings - Methods: GET, PUT, PATCH, OPTIONS Updating Clients ---------------- Client details may be updated using the `PUT` or `PATCH` method calls. If successful, you will receive a `200 OK` response. For Example: $ curl -v https://api.makeleaps.com/api/partner/{ mid }/client/{ mid }/ \ -X PATCH \ -H 'Authorization: Bearer < ACCESS TOKEN >' \ -H 'Content-Type: application/json' \ -d '{ "client_external_id": "CLIENT-12345", "contacts": ["https://api.makeleaps.com/api/partner/{ mid }/contact/{ contact_mid }/"], "default_contact": "https://api.makeleaps.com/api/partner/{ mid }/contact/{ contact_mid }/" }'' You can delete an existing contact by updating the client that it is associated with. If when updating a client you don't include an existing contact in the `contact` array, it will be deleted from MakeLeaps. If the contact you are trying to delete is used in any documents, the deletion will fail and the server will return a `400 Bad Request` error. Deleting Clients ---------------- If a client is not referenced by any documents, it may be deleted from the client list. For example: $ curl https://api.makeleaps.com/api/partner/{ mid }/client/{ client_mid }/ \ -X DELETE -H 'Authorization: Bearer < ACCESS TOKEN >' \ If the request was successful, you will receive a `204 NO CONTENT` response. Client Organizations -------------------- In the MakeLeaps system, a `Client` is a type of organization that you do certain kinds of business with. Clients are the people and companies you do business for and so it is expected that you may want to send a quote, or invoice to them. These are also the companies you receive payment from. A client can be thought of as a group of contacts who all work together. Client Types ------------ A client may contain one or more contacts. Three types of business are currently supported: - A client with one contact of type `person` - A client with one contact of type `organization` - A client with one contact of type `organization` plus one or more contacts of type `person`. The following configurations are not supported: - A client with two or more contacts of type `organization` - A client with two or more contacts of type `person` without also having an `organization` contact. Clients that contain at least one `organization` contact will have the boolean value `is_organization=true`. Client Name ----------- A Client's name is automatically derived from the contacts it owns. If there is an contact of type `organization`, then that name will be used. If a client only consists of a single `person` contact, then the person's name will be used instead. This means adding an organization contact to a client will also change it's name. Default Contact --------------- All clients are given a default contact. When specified as a default, this contact will used as the default selection in various forms throughout the application. Archived Clients ---------------- Many companies wish to exclude clients they no longer do business with from reports without deleting them. The current archived state can be seen on each client. Client External ID ------------------ Clients can be associated with an identification number from an external system. The `client_external_id` can be any string value. This allows you to map data between MakeLeaps and other software. Creating Clients ---------------- Since clients are collections of contacts, it is required to pass the contact data along with the request. For example: $ curl https://api.makeleaps.com/api/partner/{ mid }/client/ \ -X POST \ -H 'Authorization: Bearer < ACCESS TOKEN >' \ -H 'Content-Type: application/json' \ -d '{ "client_external_id": "CLIENT-12345", "contacts": [ { "contact_type": "organization", "name": "Test Co", "addresses": [], "email": null }, { "contact_type": "person", "family_name": "Test", "addresses": [], "email": {"address": "test@example.com"} }] }' It is also possible to create the contacts you wish to use first and then create a client that references them. Once the contacts are created, they can be included by reference in the request to create a client. For example: $ curl https://api.makeleaps.com/api/partner/{ mid }/client/ \ -X POST \ -H 'Authorization: Bearer < ACCESS TOKEN >' \ -H 'Content-Type: application/json' \ -d '{ "client_external_id": "CLIENT-12345", "contacts": [ "https://api.makeleaps.com/api/partner/{ mid }/contact/{ contact_mid }/" ], "default_contact": "https://api.makeleaps.com/api/partner/{ mid }/contact/{ contact_mid }/" }' Note that the `contacts` are specified as a list, but the `default_contact` is specified as a single url. The `default_contact` must also be included in the list of `contacts`. ### Fields - **`url`** `Read-Only` - **Type**: `URL` - **`mid`** `Read-Only` - **Type**: `MakeLeaps ID` - **Description**: MakeLeaps ID - **`display_name`** `Read-Only` - **Type**: `String` - **Description**: Display Name - **`organization_type`** `Read-Only` - **Type**: `String` - **Description**: Organization Type - **`is_organization`** `Read-Only` - **Type**: `Boolean` - **Description**: Organization - **`date_archived`** `Read-Only` - **Type**: `Timestamp` - **Description**: Date Archived - **`client_external_id`** - **Type**: `String` - **Description**: External ID - **`contacts`** `Required` - **Type**: `Array of URL` - **Description**: Contacts - **`default_contact`** `Expandable` - **Type**: `URL` - **Description**: Default Contact - **`managing_teams`** `Read-Only` - **Type**: `Array of Group` - **Description**: Group - **`default_presets`** `Read-Only` `Expandable` - **Type**: `Array of Preset URL (Expandable)` - **Description**: Default Document Presets - **`integrations`** `Read-Only` - **Type**: `JSON Object` - **Description**: Relationship with external systems - **`lang_code`** - **Type**: `String` - **Description**: Language code - **`settings`** `Read-Only` - **Type**: `URL` - **Description**: Sending Settings - **`date_cutoff`** - **Type**: `Integer` - **Description**: Invoicing Cutoff - **`tax_registration_number`** - **Type**: `String` - **Description**: Client Tax Registration Number ### Extra Filters - **`archived`** - **Type**: `Boolean` - **`search`** - **Type**: `String` - **Description**: Full text search ## Client Sending Settings ### Endpoints - `/api/partner//client//settings/` - Name: Client Sending Settings - Methods: GET, PUT, PATCH, OPTIONS Client Sending Settings ------------------------ The default sending settings for a Client's Sending Orders can be updated through the Client Sending Settings endpoint for that Client. For Example: $ curl -v https://api.makeleaps.com/api/partner/{ mid }/client/{ mid }/settings/ \ -X PATCH \ -H 'Authorization: Bearer < ACCESS TOKEN >' \ -H 'Content-Type: application/json' \ -d '{ "securesend_subject": "@(document_number)", "securesend_message": "いつもお世話になっております。請求書を添付させていただきました。ご確認よろしくお願いします。", "send_by_secure_send": true, "send_by_post": true, "enable_cc_payments": false, "use_document_contact": false, "secure_send_contacts": ["https://api.makeleaps.com/api/partner/{ mid }/contact/{ contact_mid }/" }'' Note: when creating Sending Orders via the API, none of the following Client default settings are applied and all relevant Sending Order's properties must be specified in the request to the Sending Order endpoint. Following is a list of the fields and how they translate to the default settings on a new Sending Order created via the MakelLeaps UI. - `send_by_secure_send`: if true, Secure Send is checked. - `send_by_post`: if true, Send by Post is checked. - `send_to_clientinbox`: if true, Send to Client Inbox is checked. - `enable_cc_payments`: if `true`, Enable MakeLeaps Payments is checked. Note: to set as `true`, your company must have the MakeLeaps Payments feature enabled. - `use_document_contact`: Controls the Secure Send "Send to" contacts* - if `true`, "Send to" defaults to the Document's Contact. Note: if `true`, do not include the `secure_send_contacts` key in the request. - if `false`, "Send to" defaults to the Contacts that are specified in `secure_send_contacts`. - `secure_send_contacts`: specifies the default recipients of a Secure Send Order using a list of one or more Contact URL strings. Required if `use_document_contact` is `false`. ### Fields - **`securesend_subject`** - **Type**: `String` - **Description**: Subject (Secure Send) - **`securesend_message`** - **Type**: `String` - **Description**: Message (Secure Send) - **`send_by_secure_send`** `Required` - **Type**: `Boolean` - **Description**: Secure Send on/off - **`send_by_post`** `Required` - **Type**: `Boolean` - **Description**: Send by Post on/off - **`send_to_clientinbox`** - **Type**: `Boolean` - **Description**: Send via Client Inbox on/off - **`send_by_peppolsend`** - **Type**: `Boolean` - **Description**: Peppol Send on/off - **`enable_cc_payments`** - **Type**: `Boolean` - **Description**: Enable MakeLeaps Payments on/off - **`use_document_contact`** `Required` - **Type**: `Boolean` - **Description**: Use Document Contact as Secure Send addressee - **`secure_send_contacts`** - **Type**: `Array of URL` - **Description**: Contact(s) of Secure Send addressee(s) - **`peppol_participant_id`** - **Type**: `String` - **Description**: Peppol ID ## Contacts ### Endpoints - `/api/partner//contact/` - Name: Contact List - Methods: GET, POST, OPTIONS - `/api/partner//contact//` - Name: Contact Instance - Methods: GET, PUT, PATCH, DELETE, OPTIONS Contacts -------- Contacts are used throughout the MakeLeaps system as a way of representing personal data. Contact Types ------------- Contacts may be of type `person` or `organization` depending on what they represent. Personal contacts use the `family_name` and `given_name` fields, while Organizational contacts use the `name` field. Localization ------------ MakeLeaps is a multi-lingual application that is aware of local customs for naming people and businesses, honorifics, addressing, and other regional differences. Many of these features are present in the Contact object. MakeLeaps will try to make intelligent choices about how to best represent that name for display as the `format` field. The result of this guess is shown in the `display_name` field. Addresses --------- We only allow one address per contact, however this may change in the future. Currently, if you would like to have multiple addresses, you will need to create a new contact for each one. For this reason addresses must be specified as nested within a list. Addresses should be specified along with a `country_name` and `format` value. The country name should be the two letter country code. The `format` field should indicate how the address will be printed. For example, Japanese addresses may be written in a Japanese style: 〒153-0061 東京都目黒区中目黒3-1-5 YK中目黒ビル2F The same address may be written in a Western style: YK Nakameguro Building 2F 3-1-5 Nakameguro, Meguro-ku Tokyo 153-0061 Both addresses represent the same building, but would be appropriate on different documents. The `region` field on JP addresses should be a prefecture name in lowercase roman characters. This helps make it easily selectable in the MakeLeaps UI. For example, a Tokyo address would be set with region set as `tokyo`. Ownership --------- Contacts will usually be owned by an Organization in the app (client, partner or vendor) but can be created without an owner and later assigned to one. The `owner` and `owner_type` fields link to the owning object but are not explicitly set when creating the contact. Please note that both of these fields are read-only. Creating Contacts ----------------- Contacts can be created with a `POST` method which will return a status of `201 CREATED` and a url where the object can be found. For example: $ curl https://api.makeleaps.com/api/partner/{ mid }/contact/ \ -X POST \ -H 'Authorization: Bearer < ACCESS TOKEN >' \ -H 'Content-Type: application/json' \ -d '{"contact_type": "organization", "name": "Test", "family_name": "",\ "given_name": "", "title": "", "department": "", "format": "default",\ "phone_number": "", "email": null, "addresses": [\ {"format": "jp_default", "country_name": "JP", \ "street_address": "0-0-0", "extended_address": "サンプルビル１階", \ "locality": "渋谷区恵比寿", "region": "tokyo", \ "postal_code": "000-0000"\ }\ ]}' Contacts -------- Contacts are used throughout the MakeLeaps system as a way of representing personal data. Updating Contacts ----------------- Contact details may be updated using the `PUT` or `PATCH` method calls. If successful, you will receive a `200 OK` response. For example: $ curl -v https://api.makeleaps.com/api/partner/{ mid }/contact/{ mid }/ \ -X PATCH \ -H 'Authorization: Bearer < ACCESS TOKEN >' \ -H 'Content-Type: application/json' \ -d '{"name": "New Name"}' Deleting Contacts ----------------- Contacts may only be deleted if they are not being referenced by another object. You may have to delete the `owner` object before you can delete a contact. If the contact has no owner object, you can delete it. Contacts without owners, do not show up in the MakeLeaps user interface, but this may not always be the case in the future. For example: $ curl -v https://api.makeleaps.com/api/partner/{ mid }/contact/{ mid }/ \ -X DELETE \ -H 'Authorization: Bearer < ACCESS TOKEN >' \ -H 'Content-Type: application/json' If the request was successful, you will receive a `204 NO CONTENT` response. You can also delete contacts by updating the client that it is associated with. See the Updating Clients section for more information. ### Fields - **`url`** `Read-Only` - **Type**: `URL` - **`mid`** `Read-Only` - **Type**: `String` - **Description**: MakeLeaps ID - **`owner`** `Read-Only` - **Type**: `Client URL` - **Description**: Owner - **`owner_type`** `Read-Only` - **Type**: `One of ['partner', 'client', 'vendor']` - **Description**: Owner Type - **`contact_type`** `Required` - **Type**: `One of ['organization', 'person']` - **Description**: Contact Type - **`name`** - **Type**: `String` - **Description**: Company Name - **`family_name`** - **Type**: `String` - **Description**: Family Name - **`given_name`** - **Type**: `String` - **Description**: Given Name - **`display_name`** `Read-Only` - **Type**: `String` - **Description**: Display Name - **`title`** - **Type**: `String` - **Description**: Title - **`department`** - **Type**: `String` - **Description**: Department - **`format`** `Read-Only` - **Type**: `One of ['default', 'jp']` - **Description**: Name Format - **`phone_number`** - **Type**: `String` - **Description**: Phone Number - **`fax_number`** - **Type**: `String` - **Description**: Fax Number - **`is_default`** `Read-Only` - **Type**: `String` - **Description**: Default Contact - **`email`** `Required` - **Type**: `Email Address` - **Description**: Email - **`addresses`** `Required` - **Type**: `Array of Address` - **Description**: Addresses - **`default_address`** `Read-Only` - **Type**: `HTML representation of Address` - **Description**: Addresses - **`integrations`** `Read-Only` - **Type**: `JSON Object` - **Description**: Relationship with external systems ### Extra Filters - **`search`** - **Type**: `String` - **Description**: Full text search