The MakeLeaps API allows you to easily access your data. You can use it to integrate with existing systems.

Please read the Notice regarding MakeLeaps API usage section first.

Environments

We provide two endpoints for automated access to the MakeLeaps system:

• api.makeleaps.com - Production data (JSON API)
• app.makeleaps.com - Production data (User Browsable Web)

Automated access to the main application server (app.makeleaps.com) should be avoided.

Identifiers

Top-level objects in MakeLeaps are given special unique id's that we refer to as a mid (MakeLeaps ID). These identifiers are not sequential and the scheme may change in the future.

Most requests are keyed based on your partner ID. Requests will look like:

GET https://api.makeleaps.com/api/partner/{ mid }/documents/

Our API uses the HATEOAS design. When referencing an existing object (for example, if you wanted to say that a document is owned by an existing client), you should use the client's url in the JSON that you send to specify it.

Throttling

Currently we allow 120 requests per minute but we may raise or lower the throttle depending on server load. You can look for the Retry-After header that is sent along with the responses:

Retry-After: 53

If you are throttled, you will have to wait to make more requests. You can use the parameter to tell you how long you should sleep() to stay under the limit.

There is also a daily limit to how many requests you may make. That is currently set to 5000/day but again, we reserve the right to change it depending on usage patterns and performance.

Numeric Values

Note that decimal numeric values should be submitted as quoted strings, not as literals. This prevents errors in rounding when parsing strings and maintains precision.

Example JSON:

{
    "quantity": "3",
    "tax_rate": "5.00",
    "unit_cost": "1.17"
}

Dates and Times

Date, time and datetime should be submitted as iso-8601 formatted dates. Timestamps will be returned with microsecond precision and use the T seperator and Z format to indicate the timezone offset: 2013-11-15T06:10:21.602Z. Datetimes in MakeLeaps will generally be returned in UTC.

Example JSON:

{
    "date_due": "2011-05-11",
    "date_paid": "2011-11-11T15:00:00Z"
}

Errors

Error messages provided by the API are meant to be displayed to end-users. However, the text itself might change without notice, so avoid writing error-handling code that checks against the exact text of the error.

When creating or updating data through the API, you should always confirm that your request was successful by checking the status of the response.

You can confirm the status of the response via one of the following:

• Check the HTTP response code (recommended)
• Check the "status_code" property on the "meta" dictionary in the response

(Some API endpoints include the "status" property for historical reasons, but this field nor its presence should not be relied upon)

In the case of an error from user-behaviour (4xx response), the "response" dictionary will include error information to tell you of what mistake is being made.

The following is an example of an error when attempting to create a document after forgetting a required field and having an invalid format for the date:

{
    "meta": {
        "status_code": 400
    },
    "response": {
        "currency": [
            "This field is required."
        ],
        "date": [
            "Date has wrong format. Use one of these formats instead: YYYY[-MM[-DD]]."
        ]
    }
}

By default error messages from the API will be in English. However, if you pass in the Accept-Language header as ja, you can receive translated error message like what follows:

{
    "meta": {
        "status_code": 400
    },
    "response": {
        "currency": [
            "このフィールドは必須です"
        ],
        "date": [
            "日付の形式が違います。以下のどれかの形式にしてください: YYYY[-MM[-DD]]。"
        ]
    }
}

Generally, errors will point to specific fields that caused the issue, but in certain situations the error will not be related to a specific field. In this case a special "non_field_errors" property will be included in the response, with an error message detailing the problem.

{
    "meta": {
        "status_code": 400
    },
    "response": {
        "non_field_errors": [
            "A document with type 'invoice' and number '011' already exists."
        ]
    }
}

(In Japanese)

{
    "meta": {
        "status_code": 400
    },
    "response": {
        "non_field_errors": [
            "書類番号011のinvoiceがすでにあります。別の書類番号をお選びください。"
        ]
    }
}

Error responses may also include a mix of field and non_field_errors:

{
    "meta": {
        "status_code": 400
    },
    "response": {
        "currency": [
            "This field is required."
        ],
        "non_field_errors": [
            "A document with type 'invoice' and number '011' already exists."
        ]
    }
}

For 5xx errors, details of the error will be provided in the 'detail' key. However, such a status code is likely an issue with MakeLeaps' systems. If you are persistently getting 5xx errors, please contact support with details of how you are using the API, so we can further investigate.

Searching

Certain views support full text search on their resources. This can help you find resources through a fuzzy search in certain situations.

This full text search is enabled via a ?search= query parameter. For example, to do a search of documents containing the text makeleaps, you could search with:

GET /api/partner/<partner_mid>/document?search=makeleaps

Full text search is currently enabled for several list endpoints. See "Extra Fiters" table in each endpoint description.

Please contact us if there are any endpoints you would like to see added.

Filtering of List Views

Certain resources have fields that are filterable. By adding a query string (e.g. ?date=2023-07-19) to the URL, the list view of certain resources can be filtered based on the values of certain fields.

Below are our different filtering options. Please contact us if there are any fields or filtering methods you would like added.

Single parameter filtering

In your query string, specify the field and the target value you want to filter by, and only objects that fulfill the "field=target" condition will be returned. The fields for which this is enabled are indicated in the standard field tables by the funnel icon. Fields listed in the "Extra filters" tables can also be used in the same way.

Example: Documents are filterable by document_type, so you can filter your Document GET result to only Documents of type invoice using:

GET /api/partner/<partner_mid>/document/?document_type=invoice

Multiple parameter filtering

In your query string, string together multiple field=target pairs using &. Any objects that fulfill ALL conditions will be returned (AND logic). Any filterable field can be included in a multi-parameter filter.

Example: Documents are filterable by document_type and date, so using the following, you can filter your Document GET result to Documents of type invoice that ALSO have an issue date of July 19, 2023 by using the following:

GET /api/partner/<partner_mid>/document/?document_type=invoice&date=2023-07-19

Filtering using multiple values for a single parameter (comma-separated)

By using a single parameter in your query string and passing multiple values in a comma-separated list, you can filter to objects that have ANY ONE OF THOSE values (OR logic). The fields for which this is enabled are marked Multi-value OR filter (comma-separated) in the appropriate tables.

Example: Documents are filterable in this way using the tags field, so you can filter your Document GET result to any Documents that have either 2021 or 2022 tag with the following:

GET /api/partner/<partner_mid>/document/?tags=2021,2022

Filtering using multiple values for a single parameter (repeat parameter)

By including certain parameters multiple times in your query string and passing different values each time, you can filter to objects that have ANY ONE OF THOSE values ("OR" logic). The fields for which this is enabled are marked Multi-value OR filter (repeat parameter) in the appropriate tables.

Example: Documents are filterable in this way via the document_number field, so you can filter your Document GET result to Documents that have numbers INV-1234 or INV-5678 with the following:

GET /api/partner/<partner_mid>/document/?document_number=INV-1234&document_number=INV-5678

Filtering Documents by dates or timestamps using before/after

Supported filters on Document dates and timestamps are as follows, usable by appending to the field name. Note: for Date fields, use only the date part of ISO-8601 format (e.g. 2020-01-01), but for Timestamp fields you need to include time through minutes (seconds and time zone are not required, e.g. 2020-01-01T00:00).

• __lt: Less than (strict)
• __lte: Less than (inclusive)
• __gt: Greater than (strict)
• __gte: Greater than (inclusive)

Examples:

# documents with a date of June 20th 2017
GET /api/partner/<partner_mid>/document/?date=2017-06-20
# documents with a date less than or equal to June 20th 2017
GET /api/partner/<partner_mid>/document/?date__lte=2017-06-20
# documents with a date between June 20th 2017 and July 1st 2017
GET /api/partner/<partner_mid>/document/?date__gte=2017-06-20&date__lt=2017-07-01

Expansion

Certain views have fields that support expansion. When a field is expanded, its value will be the entire resource, instead of just a URL returning a resource.

For example, the Document Instance View has a client field that can be expanded by passing the ?expand=client query parameter to the request. If this parameter is passed, then the result will be:

{
    "document_type": "invoice",
    "client": {
        "display_name": "Sample Company",
        [...]
    },
    [...]
}

Multiple fields can be expanded within the same request. For example, to expand the client and client_contact fields at once, pass the ?expand=client,client_contact parameter.

Only top-level fields can be expanded, however.

Please contact us if there are any fields that you would like to have expanded.

Language

Most fields in MakeLeaps only have one value, so specifying a language in the request will not change the API's response, but some fields do have bilingual variants. If a field has bilingual variants, the default value returned by the API will be the English version. The Japanese version can be accessed by passing the Accept-Language request header as ja.

Examples of values for different fields with different Accept-Language settings:

• name field of Partner resource
  • no header: returns "English Name" value set in the My Company screen.
  • ja: returns "Japanese Name" value set in the My Company screen.
• display_name field of Document, Received Document, and Accepted Order
  • no header: returns string containing English Document Type name, " #", and the Document Number, e.g. "Invoice #101".
  • ja: returns string containing Japanese Document Type name, "番号", and the Document Number, e.g. "請求書番号101".

Authentication

All requests to the MakeLeaps API must be made with an access token and be TLS/SSL encrypted. The requests will be associated with an API key you can create in the MakeLeaps API page.

To access the API, you will be using OAuth2 with a client_credentials grant. Client credentials is a simplified version of OAuth2 designed specifically for backend systems which avoids some of the more complex redirection that you may have seen when working with OAuth2 in the past.

In this mode, you will be using your OAuth2 client_id and client_secret to authenticate and obtain a token. This token is what the API accepts for proof that you have access to your company. Both the client_secret and the token must be kept secret. Since you can always get a new token and they periodically expire you should never save them. You can simply request a new one when your program starts running.

Authentication Headers

When authenticating to the oauth url you should send the following headers:

POST /user/oauth2/token/ HTTP/1.1
Host: api.makeleaps.com
Accept: application/json
Authorization: Basic: < BASIC AUTH CREDENTIALS >

As described in the Basic Auth spec, the basic auth credentials should be the userid and password, separated by a single colon (":") character, as a base64 encoded string. Most libraries have basic auth built in.

Only the first reqeust to get an access token requires basic auth. When making a request to the api endpoints, you should use the following headers:

GET /api/ HTTP/1.1
Host: api.makeleaps.com
Accept: application/json
Authorization: Bearer: < ACCESS TOKEN >

Authentication Example

To demonstrate we will be using the curl command line utility. To get started, copy your API client_id and client_secret out of the application and make a request to the authentication url. You can add --trace-ascii - to any of the commands below to get better debugging output.

The authentication request should use basic auth to pass the client_id and client_secret as the username and password. These are the values you have copied from the MakeLeaps application:

$ curl -v https://api.makeleaps.com/user/oauth2/token/ \
-X POST \
-u "CLIENT_ID:CLIENT_SECRET" \
-d "grant_type=client_credentials"

{"access_token": "0a1b2c3d4e5f6g7h8i9j0k", "token_type": "Bearer", "expires_in": 36000, "scope": "read write"}

The authentication url will return an access_token (sometimes also called a 'Bearer Token' in the OAuth2 documentation) for you to use. This token can be used to make a request to any API url by setting it in the header of your requests. For example, let's try using it on the root url of the API:

$ curl -v https://api.makeleaps.com/api/ \
-X GET \
-H 'Authorization: Bearer 0a1b2c3d4e5f6g7h8i9j0k'

{
    "meta": {"status": 200},
    "response": {
        "partners": [{
            "url": "https://api.makeleaps.com/api/partner/{ mid }/",
            "name": "TEST COMPANY"}],
        "currencies": "https://api.makeleaps.com/api/currency/"
    }
}

If something is wrong with your credentials, you may get a response such as:

{"status_code": 401, "detail": "Authentication credentials were not provided."}

In this case, please check that your code is sending the headers as described above.

Revoking Tokens

If one of your tokens was compromised, you can revoke it using the revoke-token endpoint:

$ curl https://api.makeleaps.com/user/oauth2/revoke-token/ \
-X POST \
-u "CLIENT_ID:CLIENT_SECRET " \
-d "token=0a1b2c3d4e5f6g7h8i9j0k"

If your client_id or client_secret were comprimised, you can head to the MakeLeaps API page to revoke the API Key.

Creating Objects

If a URL endpoint reports that it supports POST, PATCH, PUT, or DELETE values, then you may use the API to modify your data.

When objects are created, you should send in data as json by specifying the Content-Type: application/json header. For example:

$ curl -v https://api.makeleaps.com/api/partner/{ mid }/contact/ \
-X POST \
-H 'Authorization: Bearer 0a1b2c3d4e5f6g7h8i9j0k' \
-H 'Content-Type: application/json' \
-d '{ ... }'

{ ... "url": "https://api.makeleaps.com/api/partner/{ mid }/contact/"}

The response will usually be a status code of 201 CREATED along with the json representation of the object created including a url value to request more details about the object that was created.

Access Token Expiration

The access_token used to access the API has a limited lifetime. After expiring, it will not longer be valid for making requests and you will have to reauthenticate to get a new one. You can either keep track of the token's expiration time using the expires_in value or simply wait until it expires and reauthenticate.

Money fields are represented as strings (instead of numbers), in order to avoid floating-point related rounding errors. Money fields are often paired with currency fields.

For example, on the document field, to represent a document with a 5000 Yen total, you would pass in:

{
    ...
    "currency": "JPY",
    "total": "5000"
}

Supported Currencies

These currencies are officially suported. Please contact support if a currency you would like to use is not yet supported.

Your Company

Your company is represented by a Partner object. This object also contains the endpoints for the resources of this company.

If you've been invited to work in several companies, your user account may be associated with multiple partners. However, the API keys may only be associated with and access one Partner at a time.

Because API keys are currently restricted to a single company, the simplest way to get started is to query the Partner List and find your company there.

Employees represent the team members of your company.

Documents

Documents are the heart of our system. They are filled out by users and sent to clients, either by post or using Secure Send.

Document Types

The following document types are available. Depending on your company's current setup, some might not be available to you:

• order for orders
• quote for quotes
• orderslip for order slips
• orderconfirmation for order confirmations
• deliveryslip for delivery slips
• acceptance for acceptance certificates
• invoice for invoices
• receipt for receipts
• timesheet for timesheets

Document Templates

Document templates define the style of the PDFs that get generated for documents. The list of available document templates for a specific document_type can be retrieved with the following command:

$ curl -v https://api.makeleaps.com/api/partner/{ mid }/template/{ document_type }/?hide_archived=y&is_archived=false \
-X GET \
-H 'Authorization: Bearer < ACCESS TOKEN >' \

{
    "meta": {
        "status": 200
    },
    "response": [
        {
            "template_code": "ja_JP_pro_4",
            "document_type": "invoice",
            "display_name": "[JA] Professional",
            "language_code": "ja"
        }
    ]
}

Document Autocalculation

When creating and updating documents, it is possible to calculate the total, subtotal, tax, jp_withholding_tax, subtotal_sales_tax, subtotal_withholding_tax, mixed_tax_rate_totals fields and the 'price' for normal line items directly via the autocalculate field.

When specifying the "autocalculate": true field, the total, subtotal, tax and jp_withholding_tax fields and the price field on the line items should be removed, as they will be overwritten by the autocalculation. Otherwise the API will produce an error. The subtotal_sales_tax, subtotal_withholding_tax and mixed_tax_rate_totals fields will simply be overwritten by the autocalculation.

Totals with Mixed Tax Rates

(*) This field is only used for the v4 templates, other templates will not use these values.

Multiple tax and subtotal amounts for different tax rates can be stored on the document by specifying the mixed_tax_rate_totals field. Each tax rate needs to be specified as a key with its value a dictionary containing the subtotal and/or tax in a money format, otherwise the API will produce an error.

Example JSON for handling mixed tax rate totals with 8% and 10%:

{
    "mixed_tax_rate_totals": {
        "8": {
            "subtotal": {"amount": "10000", "currency": "JPY"},
            "tax": {"amount": "800", "currency": "JPY"}
        },
        "10": {
            "subtotal": {"amount": "10000", "currency": "JPY"},
            "tax": {"amount": "1000", "currency": "JPY"}
        }
    }
}

If autocalculate is true, then the document mixed_tax_rate_totals field will automatically be built from the different line item tax rates and values.

The group_lineitem_by_tax_rate field controls which style the taxes and subtotals are displayed on the v4 templates PDFs. If it's set to true then the line items will automatically be grouped by tax rates on the PDFs.

When the group_lineitem_by_tax_rate is false, and the document has both items with 8% tax rate and items with 10% tax rate, trailing ※ on each 8% items and a message like '※: Reduced tax rate of 8% applied' below the item table will be automatically added. If you would like to hide them, set hide_tax_description to true.

Document Extended Data

Additional data can be stored on a Document by specifying the extended_data dictionary. The keys that can be used in the extended_data dictionary depend on the selected Document Template. If a particular field is not on the chosen template, an error will be returned by the API.

Setup:

In order to store data in Extended Data Fields (extended_data) on a Document, you must specify an Document Template that references those Extended Data Fields, such as the following:

MakeLeaps' Client Balance Templates (codes end with client_balance) support the following Document Extended Data Fields.

• ml_amount_to_pay
• ml_carryover
• ml_adjustment
• ml_last_paid_amount
• ml_last_invoice_amount

User-Defined Templates can be created referencing the above Extended Data Fields or your own custom fields. A User-Defined Template must be published before you can use it to make a Document. You can learn more about User-Defined Templates and creating custom Extended Data Fields in the MakeLeaps Help Center.

The structure of the extended_data dictionary is as follows, where key1, key2, etc are the "Keys" defined for each Extended Data Field, and the <value1> etc is the value you wish to store for the Field. (See below about how to set values for different Fields with different Data Types.)

"extended_data": {
  "key1": <value1>,
  "key2": <value2>,
  ...
}

Other notes:

• The combined length of keys and values set to the extended_data dictionary must not exceed 600 characters (double-byte characters also count as 1 character).
• Since the number of Document Extended Data Fields that can be used on a template is limited to 10, you cannot have more than 10 keys in the extended_fields dictionary.
• Extended Data Field input is not mandatory, so failure to provide values for some or all the Extended Data Fields that exist on the Document Template will not result in an error.

How to pass values for different Data Types:

• Money type field: requires a valid money dictionary containing amount and currency keys specified with string literal values. Note that the value for currency (e.g. "JPY") must match the Document's currency.

  { "amount": "1000", "currency": "JPY" }

• Date type field: the value must be a in a valid date format, and should not include time. Please refer to the Dates and Times section on how to pass a date in the correct format.

• Text type field: the value must be string literal. String must be no more than 40 characters in length.

  { "note": "MX-0001239", }

Example JSON for handling additional data via the extended_data field, using a Client Balance template and the MakeLeaps pre-loaded Extended Data Fields.

{
    "document_template": "ja_JP_pro_4_windowed_client_balance",
    "extended_data": {
        "ml_last_invoice_amount": {"currency": "JPY", "amount": "10000"},
        "ml_last_paid_amount": {"currency": "JPY", "amount": "9000"},
        "ml_adjustment": {"currency": "JPY", "amount": "1000"},
        "ml_amount_to_pay": {"currency": "JPY", "amount": "1000"}
    }
}

Document Marking

When updating a document, it is possible to mark it through the API by specifying the corresponding date:

• date_paid: to mark as paid

• date_cancelled: to mark as cancelled

• date_sent: to mark as sent

• date_confirmed: to mark as confirmed

• date_accepted: to mark as accepted

Please refer to the Dates and Times section on how to pass a date in the correct format.

Example JSON to mark a document as paid:

{
    "date_paid": "2018-03-30T12:00:00+09:00"
}

Passing a null date will unmark a document if it has been marked previously. For example, to unmark as paid:

{
    "date_paid": null
}

Depending on the document type, the date might not be supported, in that case the API will produce an error. Here's a list of the current supported dates by document types:

• Order: date_sent, date_cancelled, date_valid

• Quote: date_sent, date_cancelled, date_paid, date_accepted, date_valid

• Order Slip: date_sent, date_cancelled, date_paid, date_accepted, date_paid

• Order Confirmation: date_sent, date_cancelled

• Timesheet: date_sent, date_cancelled

• Delivery Slips: date_sent, date_cancelled, date_shipped

• Acceptance Certificate: date_sent, date_cancelled, date_confirmed

• Invoice: date_sent, date_cancelled, date_paid, date_due

• Receipts: date_sent, date_cancelled

Line Items

Line Items are mainly used when creating or reading documents.

To order the line items on the document, please make sure to assign the position field to determine the ordering of a set of items.

Line Item Type

The following line item types are available (and assigned to kind):

• normal for a normal line item, that shows all the fields
• simple for a line item that only has a description and an amount field
• text for a line item with only a description, and no money amount
• subtotal When autocalculate is on, the subtotal is calculated as the total of preceding line items, either from the top of the table, or from the previous subtotal line if one exists.

Source catalog Item

The source_catalog_item field can be used to set default values for the different fields when creating a line item of type simple or normal. The line item fields other than kind and source_catalog_item must be omitted in order for the catalog item values to be used.

Tax Rate

A tax rate can be set on the line item as a numeric value.

The line item tax_rate can be used in combination with the document autocalculate field when assigning the line item to the document: If autocalculate is true, then the document mixed_tax_rate_totals field will automatically be built from the different line items tax rate and values.

By omitting the tax_rate field and specifying the source_catalog_item field, the tax rate will be set from the catalog item tax_category value. Refer to the Tax Category section on the different behavior of the catalog tax_category field.

If both fields are omitted, the line item will use the value of the document tax_rate field when assigned to a document, otherwise the company default tax rate will be used.

Line Item Extended Data

Additional data can be stored on each line item by specifying the extended_data dictionary.

Please refer to the Document Extended Data section about how to handle each data type of additional data.

Example JSON for handling additional data via the extended_data field on a line item:

{
    "document_template": "TPL12345678910",
    "lineitems: [
        {
          "description": "MX",
          "has_jp_withholding_tax": false,
          "is_tax_inclusive": false,
          "is_taxable": true,
          "kind": "simple",
          "position": 0,
          "price": "1000",
          "quantity": "1",
          "quantity_unit": "",
          "unit_cost": "1000"
          "extended_data": {
            "note": "MX-0001239",
            "purchase_date": "2023-04-01",
            "additional_charge": {"currency": "JPY", "amount": "1000"}
          }
        }
    ]
}

The Line Item Catalog is used to save line items for future use on documents. This is useful for reporting and for keeping track of "standard" products that your company might sell.

The resources in the Line Item Catalog resemble Line Items, except with a couple extra fields.

Product Code

Product codes are unique identifiers for entries in the Line Item Catalog. It is not required, but recommended, and used when generating reports.

You can filter results by product code.

- `?product_code=ABC` will filter for an exact match.
- `?product_code__contains=ABC` will filter for product codes that include the text `ABC` somewhere inside.

Tax Category

The tax_category field is used when specifying the source_catalog_item field and omitting the tax_rate field when creating a line item. It can take one of the following values:

• default: use the company default tax rate
• alternate: use the company alternate tax rate if it was set, otherwise the company default tax rate
• custom: use the tax_rate specified on the catalog line item

When using a custom tax category, a tax_rate value must be provided. When assigning a line item with a source_catalog_item to a document, if there is no tax_category set or the tax_category is null, then the document tax_rate value will be used.

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.

Client Document Settings

Client's default sending methods for documents and Secure Send options 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 }/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 }/"
}''

enable_cc_payments setting: In order to set as true, your company must have the MakeLeaps Payments feature enabled.

use_document_contact setting: Controls which contacts will receive a document when a user initiates a send from the MakeLeaps interface*.

• If setting to true, document is sent to Document's Contact. Please do not include the secure_send_contacts key in the data.

• If setting to false, document is sent to Client's Contacts. Specify an array of Client contact(s) to receive documents using the secure_send_contacts key.

(*) Note: the use_document_contact setting does not affect who receives documents that are sent via the API.

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.

Document Archive

Document Archive preserves copies of MakeLeaps Documents as they appeared once sent to their respective recipients, in order to assist with compliance with 電子帳簿保存法 (note: a law in Japan to define the regulations of electronic record retention).

A Document Archive can be created as follows:

• when a MakeLeaps Document is sent using MakeLeaps sending list, a record is automatically created using the Document data that was sent.
• when a user uses "Mark as Sent" in the MakeLeaps UI and chooses to create an Archive. The Archive stores the Document data as it was when it was marked as sent.
• by making a request via this API (see below).

Sample data (GET):

{
    "meta": { "status": 200, "status_code": 200 },
    "response": {
        "mid": "1234567890",
        "url": "http://api.makeleaps.com/api/partner/<partner_mid>/archive/1234567890/",
        "pdf_content_url": "http://api.makeleaps.com/api/partner/<partner_mid>/archive/1234567890/pdf/",
        "uses_external_pdf": false,
        "document_type": "receipt",
        "document_number": "REC202302/08-OC585",
        "sending_methods": ["manually_sent_electronically"],
        "legal_categories": ["electronically_outside_makeleaps"],
        "date_sent": "2023-03-23T04:20:56.181801Z",
        "date": "2023-02-11",
        "sender": "Employee Name",
        "client": "Client Name",
        "currency": "JPY",
        "total": "1000",
        "external_id": ""
    }
}

sending_methods of a Document Archive indicates the method by which the Document was sent.

• secure_send: sent by Secure Send via MakeLeaps.
• japan_post: sent by Japan Post via MakeLeaps.
• manually_sent_electronically: sent electronically outside MakeLeaps
• manually_sent_physically: printed and sent paper copy outside MakeLeaps

legal_categories of a Document Archive reflects the delivery category defined in 電子帳簿保存法.

• electronically_from_makeleaps: sent using any electronic method via MakeLeaps
• physically_from_makeleaps: sent using any printed paper copy via MakeLeaps
• electronically_outside_makeleaps: sent using any electronic method outside MakeLeaps
• physically_outside_makeleaps: sent using any printed paper copy outside MakeLeaps

Create Document Archive

You can create a Document Archive record for a Document that will save its current state by sending a POST request. In your request, the following must be specified:

• document_mid: the MID of the target Document. The Document must already have a value for date_sent.
• sending_method: the sending method used when the Document was sent. Only manually_sent_electronically and manually_sent_physically can be specified when you create a Document Archive via the API.

Sample request:

$ curl https://api.makeleaps.com/api/partner/<partner_mid>/archive/create/ \
-X POST \
-H 'Authorization: Bearer < ACCESS TOKEN >' \
-H 'Content-Type: application/json' \
-d '{"document_mid": "1234567890", "sending_method": "manually_sent_electronically"}'

If the creation is successful, the endpoint will return the newly created Document Archive as a response.

Note:

• Document Archive creation is not supported for Acceptance Certificates and Order Slips.
• You cannot specify the date_sent datetime of the Archive record. It will be timestamped with the datetime the request was received.

Sending Orders

MakeLeaps currently supports sending documents via the Secure Send feature and via Japan Post. A Sending Order is a request to send a set of documents through one or both of those methods.

The flow to successfully send documents is as follows:

1. Create a Sending Order with the desired options.
2. Attach one or more Sending Order Items to the Sending Order.
3. Wait for the system to validate the Sending Order to make sure it is sendable. Make any needed corrections if it isn't.
4. Execute the Sending Order.

After a Sending Order has been executed, depending on the selected sending options and current status, it may be possible to cancel it.

Creating a Sending Order

POST /api/partner/<partner_mid>/sending/order/

Sample data:

{
    "recipient_organization": <client_url>,
    "securesend_selected": true,
    "to_emails": ["myclient@example.com"],
    "subject": "Invoices for August",
    "message": "Invoices are attached. Thank you for your business.",
    "enable_cc_payments": true,
    "sendbypost_selected": true,
    "stamp_type": "invoice",
    "recipient_contact_organization_name": "My Client",
    "recipient_contact_department": "Accounts Dept.",
    "recipient_contact_title": "Director",
    "recipient_contact_name": "Jane Smith",
    "recipient_honorific": "様",
    "recipient_address": {
        "address_format": "jp_default",
        "country": "JP",
        "street_address": "Main St.",
        "extended_address": "ABC Bldg. #123",
        "locality": "Shinjuku-ku",
        "region": "tokyo",
        "postal_code": "000-0000"
    },
    "sender_contact_organization_name": "My Company",
    "sender_contact_phone_number": "12-3456-7890",
    "sender_address": {
        "address_format": "jp_default",
        "country": "JP",
        "street_address": "Main St.",
        "extended_address": "ABC Bld.g #456",
        "locality": "Shinjuku-ku",
        "region": "tokyo",
        "postal_code": "000-0000"
    },
    "status": {
        "url": "<status url>",
        "securesend": "not_viewed",
        "sendbypost": "preparing",
        "securesend_cancelled": false,
        "sendbypost_cancelled": false
    },
}

General options

These options apply to any selected sending method.

• recipient_organization

Secure Send Options

These options are related to Secure Send and don't affect Japan Post.

• securesend_selected
• to_emails
• subject
• message
• enable_cc_payments

Japan Post Options

These options are related to Japan Post and don't affect Secure Send.

• sendbypost_selected
• stamp_type
• recipient_contact_organization_name
• recipient_contact_department
• recipient_contact_title
• recipient_contact_name
• recipient_honorific
• recipient_address
• sender_contact_organization_name
• sender_contact_phone_number
• sender_address

Adding and deleting Sending Order Items

Adding an in-app document

POST <items_url>

Sample data:

{
    "position": 0,
    "document": <document_url>
}

Adding a custom file

First, add the item.

POST <items_url>

Sample data:

{
    "position": 1,
    "filename": "flyer.pdf"
}

Then, upload the file.

PUT <upload_url>

Sample headers and data:

Content-Type: 'multipart/form-data; boundary=----------a_BoUnDaRy759443597973$'

------------a_BoUnDaRy759443597973$
Content-Disposition: form-data; name="content_file"; filename="filename.pdf"
Content-Type: application/pdf

<PDF file contents>

------------a_BoUnDaRy759443597973$--

Deleting an item

DELETE <item_url>

Executing an order

If the ready_to_order field of a Sending Order is not true, it's not possible to send it. It may be that it's still being validated by the system, or it may be that there are problems with the selected options and they need to be modified. Any problems in the order will be listed in the validation_errors field.

To execute the Sending Order when it's ready:

POST <send_url>

Sample data:

{
}

Tracking the status of an order

The status field contains information about the latest status of each selected sending method, and an URL for cancellation.

{
    "url": "<status url>",
    "securesend": "not_viewed",
    "sendbypost": "preparing",
    "securesend_cancelled": false,
    "sendbypost_cancelled": false
}

Secure Send

Possible values for the securesend field are:

• draft - Sending Order has not been executed.
• not_selected - Secure Send is not selected.
• cancelled - Sent by Secure Send, but cancelled before recipient viewed it.
• viewed - Sent by Secure Send and already seen by recipient.
• not_viewed - Sent by Secure Send, but not yet seen by recipient.

Send by Post

Possible values for the sendbypost field are:

• draft - Sending Order has not been executed.
• not_selected - Send by Post is not selected.
• cancelled - Asked to send by Japan Post, but cancelled before 30 minutes passed. The document will not be sent by Japan Post.
• can_cancel - Asked to send by Japan Post, but the order can be cancelled.
• mailed - Asked to send by Japan Post. The document was printed and mailed.
• info_not_available - Information about this order is unavailable.
• preparing - Asked to send by Japan Post. Currently being prepared for mailing.

Cancelling after sending

If the Sending Order had more than one sending method selected, you can cancel all or selectively cancel a single one.

POST <status_url>

Sample data:

{
    "securesend_cancelled": true,
    "sendbypost_cancelled": false
}

History

History entries record past actions within our system. They are automatically created when certain actions are taken by users, such as creating, editing or deleting a document.

Filtering by Date

History entries can be filtered by date in two ways; by an exact date, or by a range defined between two dates.

By a single date:

https://api.makeleaps.com/api/partner/{ mid }/history/?date={ datetime }

By a range of dates:

https://api.makeleaps.com/api/partner/{ mid }/history/?date_start={ datetime }&date_end={ datetime }

Datetimes are in the format:

yyyy-mm-ddThh:mm:ss.00Z

Secure Inbox

The Secure Inbox is where the following interactions with your Clients can be found. Entries are sorted by time_received, with the most recent Documents coming first.

About the type

• accepted_order: Ordered documents. Quotes or Orderslips where the Client clicked "Sign off" in the pickup screen after being sent with the "Enable Document Accepting For Quotes"/"Enable Document Accepting For Order Slips" setting on.
• confirmed_doc: Confirmed documents. Acceptance Certificates where the Client clicked "Sign off" in the pickup screen after being sent via Secure Send with "Enable Document Accepting For Acceptance Certs." setting on.
• received_doc: Client-sent documents. Documents that were sent to you from another MakeLeaps user that one of your users then added to your Secure Inbox.

Note on data structure:

• confirmed_doc and accepted_order types: accepted_order field is populated and received_doc is null.
• received_doc type: received_doc field is populated and accepted_order is null.

A pickup link is a URL that can be sent to the client to share a document online. You can check whether the client visited the link, as well as cancel/uncancel it.

Creating a Pickup Link

You can create the pickup link for a document by sending a POST request without a body as follows.

POST https://<hostname>/api/partner/<partner_mid>/document/<document_mid>/pickup-link/

Since MakeLeaps uses a background task to create pickup links, the response will contain the task details, not the link itself. The task details are an instance of Task. For more details about Task, see the Task section.

When the task has finished, the pickup link is ready. The pickup link created by this task can be obtained via a GET request to result_url in the Task instance. The response will look like the following. link contains the actual pickup link that may be sent to a client.

{
    "meta": {
        "status": 200
    },
    "response": [
        {
            "mid": "<share_link_mid>",
            "url": "https://api.makeleaps.com/api/partner/<partner_mid>/secureinbox/pickup-link/<mid>/",
            "cancel_url": "https://api.makeleaps.com/api/partner/<partner_mid>/secureinbox/pickup-link/<mid>/cancel/",
            "uncancel_url": "https://api.makeleaps.com/api/partner/<partner_mid>/secureinbox/pickup-link/<mid>/uncancel/",
            "created": "2021-02-03T05:28:43.271956Z",
            "link": "https://example.com/secureinbox/p/<long_hashed_string>/",
            "email": "",
            "date_clicked": null,
            "source": "Shareable Link Panel",
            "expiration_date": "2021-04-04T14:30:38",
            "is_cancelled": false,
            "created_by": "Somebody",
            "supersend": null
        }
    ]
}

Getting Pickup Links

Sending a GET request to /api/partner/<partner_mid>/document/<document_mid>/pickup-link/ returns pickup links for document specified by <document_mid> . Note that the response might be paginated.

Cancel or Re-enable a Pickup Link

You can cancel a pickup link at any time by sending a POST as follows without a body.

POST /api/partner/<partner_mid>/secureinbox/pickup-link/<pickup_link_mid>/cancel/

If you want to re-enable an expired or cancelled pickup link, send a POST as follows without a body.

POST /api/partner/<partner_mid>/secureinbox/pickup-link/<pickup_link_mid>/uncancel/

Task is the background task mechanism used by the MakeLeaps API.

Handling Background Task

Some API endpoints use a background task to process something time consuming. In that case, the API will respond with a Task instance.

{
    "meta": {
        "status": 202
    },
    "response": {
        "mid": "<task_mid>",
        "uilongtask": {
            "url": "https://api.makeleaps.com/api/taskprogress/<progress_mid>/",
            "mid": "<progress_mid>",
            "current_progress": 0,
            "max_progress": 100,
            "time_done": null,
            "finished": false,
            "errors": []
        },
        "employee": "https://api.makeleaps.com/api/partner/<partner_mid>/employee/<employee_mid>/",
        "url": "https://api.makeleaps.com/api/partner/<partner_mid>/task/<task_mid>/",
        "result_url": "https://api.makeleaps.com/api/partner/<partner_mid>/task/<task_mid>/results/",
        "completion": 0,
        "failed_chunks": [],
        "finished": null
    }
}

completion shows the progress of the task. Starting from 0 and finishing at 100 . You can check the latest status by visiting url. The result of a task can be obtained via a GET request to result_url .

GET https://<hostname>/api/partner/<partner_mid>/task/<task_mid>/results/

The fields in the response will vary for each task. The following is an example of the document pickup link generation background task.

{
    "meta": {
        "status": 200
    },
    "response": [
        {
            "mid": "<share_link_mid>",
            "created": "2021-02-03T05:28:43.271956Z",
            "link": "https://example.com/secureinbox/p/<long_hashed_string>/",
            "email": "",
            "date_clicked": null,
            "source": "Shareable Link Panel",
            "expiration_date": "2021-04-04T14:30:38",
            "is_cancelled": false,
            "created_by": "Somebody",
            "supersend": null
        }
    ]
}

Approval Requests

Approval Requests are how MakeLeaps stores Approval records of Documents. This can be either via

• Requesting Approval to a Member (Employee) or Group via "Assign to"
• Requesting Approval using an Approval Flow
• A Document being approved ad hoc by a Member with the correct permissions (possible when "Disable Direct (Non-Flow) Approval of Documents" setting is Off). In this case, the requester field will be blank.

Documents once approved can be Unapproved, but this is not recorded in Request Approvals. The final Approval status of the Document should be confirmed by referencing the approval_status field on the Document itself.

Approval Request Status

Approval Requests can have one of the following statuses.

• pending - Approval has been requested, but approval is not yet complete.
• rejected - An approver has Rejected the Document.
• approved - Request is Approved, either ad hoc or as part of the corresponding Request.
• cancelled - Request was Deleted by a User before Approval was completed.

• MakeLeaps does not offer technical support for this API. We are not responsible for answering questions about implementations using this API.
• At its discretion, MakeLeaps may provide information about the API. Doing so does not create an obligation to provide support for the API, nor liability for implementations making use of said information.
• Please refer to MakeLeaps Help Center about MakeLeaps' functionality.