MakeLeaps REST API


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

Standard format for Date and Timestamp fields is ISO 8601.

Dates and Timestamps in responses

  • Date fields: return only year, month, and day.
  • Timestamp fields: return using the T separator between date and time, generally in UTC (Z format) with up to microsecond precision. It is recommended to use a generic ISO 8601 parser.

Example JSON:

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

Dates and Timestamps in requests

  • Date fields: specify year, month, and day.
  • Timestamp fields: Varying precision and timezone offsets can be used when sending timestamps, within the following format.
YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z]

Notes:

  • Any timestamp specified without timezone or Z specified will be assumed to be UTC.
  • Any timestamp specified with a timezone will still be stored in UTC and returned in Z format in subsequent GET requests.

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


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


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


/api/currency/
Supported Currencies
OPTIONS

Supported Currencies

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

Your Company


/api/partner/
Partner List
GET OPTIONS
/api/partner/<partner_mid>/
Partner Instance
GET OPTIONS

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.

Fields Type Description
url Read-Only  URL
name Read-Only  String Name
clients Read-Only  String Clients
contacts Read-Only  String Contacts
documents Read-Only  String Documents
line_item_catalog Read-Only  String Line Item Catalog
tags Read-Only  String Tags
sending_orders Read-Only  String Sending Orders
history Read-Only  String History
integrations Read-Only  JSON Object Relationship with external systems
account_name Read-Only  String Account Name

Employees


/api/partner/<partner_mid>/employee/
Employee List
GET OPTIONS
/api/partner/<partner_mid>/employee/<mid>/
Employee Instance
GET OPTIONS
/api/partner/<partner_mid>/employee/me/
Authenticated Employee Instance
GET OPTIONS

Employees represent the team members of your company.

Fields Type Description
url Read-Only  URL
mid Read-Only  MakeLeaps ID MakeLeaps ID
name Read-Only  String Name
email Read-Only  String Email
start_date Read-Only  Timestamp Start Date
end_date Read-Only  Timestamp End Date
integrations Read-Only  JSON Object Relationship with external systems
has_seat Read-Only  Boolean Licensed
is_owner Read-Only  Boolean Owner
is_admin Read-Only  Boolean Administrator

Extra filters

These fields are also available to filter the list.

Fields Type Memo
search String Full text search

Documents


/api/partner/<partner_mid>/document/
Document List
GET POST OPTIONS
/api/partner/<partner_mid>/document/<mid>/
Document Instance
GET PUT PATCH DELETE OPTIONS

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

Fields Type Description
document_number   String Document Number
document_type   Document Type Document Type
title String Title
project_name String Project
bank_details_header String Bank Details Header
bank_details String Bank Details
message String Message
proviso String Proviso
group_lineitem_by_tax_rate Boolean Group line items by tax rate
has_hanko Boolean Display Hanko on this document
has_prices Boolean Display prices on this document
has_totals Boolean Display totals on this document
has_currency_code Boolean Display the currency code on this document
has_lineitem_tax_state Boolean Show the tax state for each line item on this document
signature Boolean Show signature field
display_tax_rate Boolean Display document tax rate
hide_tax_description Boolean Hide alternate tax description
has_tax_stamp Boolean Show tax stamp
currency Currency Currency
subtotal Money Subtotal
tax Money Tax
jp_withholding_tax Money Withholding Tax
tax_rate Number Tax Rate
subtotal_sales_tax Money Subtotal of the items Sales Tax is Applied
subtotal_withholding_tax Money Subtotal of the items Witholding Tax is Applied
total Money Total
mixed_tax_rate_totals JSON Object Totals with Mixed Tax Rates
extended_data JSON Object Extended Data
mid Read-Only  MakeLeaps ID MakeLeaps ID
document_template   Document Template Template
display_name Read-Only  String Display Name
note String Notes
external_id   String External ID
round_tax_down Boolean Round tax down
tags Array of Tag Tags
url Read-Only  URL
pickup_links Read-Only  URL Pickup Links
pdf_content_url Read-Only  URL
pdf_upload_url Read-Only  URL
client     Client URL (Expandable) Client
client_contact     URL Contact
date_paid   Timestamp Date Paid
date_sent   Timestamp Date Sent
date_cancelled   Timestamp Date Cancelled
date_removed Read-Only    Timestamp Date deleted
date_accepted   Timestamp Date Accepted
date_confirmed   Timestamp Date Confirmed
date_converted Read-Only    Timestamp Date Converted
is_accepted Read-Only  Boolean Accepted
is_confirmed Read-Only  Boolean Confirmed
is_converted Read-Only  Boolean Converted
approval_status Read-Only  One of ['approved', 'rejected'] Approval
integrations Read-Only  JSON Object Relationship with external systems
autocalculate Boolean Automatically calculate prices, taxes and totals
use_virtual_account Boolean Use Virtual Account
date   Date Date
date_due   Date Date Due
date_valid   Date Valid Until
date_shipped   Date Shipment Date
sender_name String Sender Name
sender_contact_department String Company Contact Department
sender_contact_title String Company Contact Title
sender_contact_name String Company Contact Name
sender_address_format String Company Address Format
sender_country String Company Country Name
sender_postal_code String Company Postal Code
sender_region String Company State
sender_locality String Company City
sender_street_address String Company Street Address
sender_extended_address String Company Extended Address
sender_phone_number String Company Phone Number
sender_fax_number String Company Fax Number
recipient_name String Client Name
recipient_contact_department String Client Contact Department
recipient_contact_title String Client Contact Title
recipient_contact_name String Client Contact
recipient_honorific String Recipient Honorific
recipient_address_format String Client Address Format
recipient_country String Client City
recipient_postal_code String Client Postal Code
recipient_region String Client State
recipient_locality String Client City
recipient_street_address String Client Street Address
recipient_extended_address String Client Extended Address
recipient_phone_number String Client Phone Number
recipient_fax_number String Client Fax Number
lineitems Array of Line Item Line Items
purchase_order_ids Array of String PO Numbers
source_received_document   URL Received Document URL
partner_tax_registration_number String Tax Registration Number
display_partner_tax_registration_number Boolean Display Tax Registration Number
use_external_pdf Boolean Use external PDF

Extra filters

These fields are also available to filter the list.

Fields Type Memo
document_number String Multi-value OR filter (repeat parameter)
client MakeLeaps ID
client_contact MakeLeaps ID
currency String
tags String Multi-value OR filter (comma-separated)
Multi-value OR filter (repeat parameter)
accepted Boolean
confirmed Boolean
sent Boolean
viewed Boolean
paid Boolean
cancelled Boolean

Line Items


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"}
          }
        }
    ]
}
Fields Type Description
kind Line Item Type Kind
description String Description
unit_cost Money Cost
quantity Number Qty.
quantity_unit String Units
price Money Price
is_taxable Boolean Taxable
is_tax_inclusive Boolean Tax Inclusive
has_jp_withholding_tax Boolean Wthld.
currency Currency Currency
tax_rate Number Tax Rate
extended_data JSON Object Extended Data
vendor_cost Money Vendor Cost
source_catalog_item   URL Catalog Item URL

Line Item Catalog


/api/partner/<partner_mid>/item/
Catalog Item List
GET POST OPTIONS
/api/partner/<partner_mid>/item/<mid>/
Catalog Item View
GET PUT PATCH OPTIONS

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.

Fields Type Description
kind Line Item Type Kind
description String Description
unit_cost Money Cost
quantity Number Qty.
quantity_unit String Units
price Money Price
is_taxable Boolean Taxable
is_tax_inclusive Boolean Tax Inclusive
has_jp_withholding_tax Boolean Wthld.
currency Currency Currency
tax_rate Number Tax Rate
extended_data JSON Object Extended Data
vendor_cost Money Vendor Cost
mid Read-Only  MakeLeaps ID MakeLeaps ID
url Read-Only  URL
product_code   String Product Code
interval One of ['monthly', 'bimonthly', 'quarterly', 'yearly'] Billing Interval
metered Boolean Metered
tax_category One of ['default', 'alternate', 'custom'] Tax Category

Client Organizations


/api/partner/<partner_mid>/client/
Client List
GET POST OPTIONS
/api/partner/<partner_mid>/client/<mid>/contact/
Client Contact List
GET OPTIONS
/api/partner/<partner_mid>/client/<mid>/
Client Instance
GET PUT PATCH DELETE 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.

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.

Fields Type Description
url Read-Only  URL
mid Read-Only  MakeLeaps ID MakeLeaps ID
display_name Read-Only  String Display Name
organization_type Read-Only  String Organization Type
is_organization Read-Only  Boolean Organization
date_archived Read-Only  Timestamp Date Archived
client_external_id   String External ID
contacts Array of URL Contacts
default_contact   URL Default Contact
managing_teams Read-Only  Array of Group Group
default_presets Read-Only    Array of Preset URL (Expandable) Default Document Presets
integrations Read-Only  JSON Object Relationship with external systems
lang_code String Language Code
settings Read-Only  String Document Settings
date_cutoff Integer Invoicing Cutoff

Extra filters

These fields are also available to filter the list.

Fields Type Memo
archived Boolean
search String Full text search

Contacts


/api/partner/<partner_mid>/contact/
Contact List
GET POST OPTIONS
/api/partner/<partner_mid>/contact/<mid>/
Contact Instance
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": "サンプルビル1階", \
     "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 Type Description
url Read-Only  URL
mid Read-Only  String MakeLeaps ID
owner Read-Only  Client URL Owner
owner_type Read-Only    One of ['partner', 'client', 'vendor'] Owner Type
contact_type   One of ['organization', 'person'] Contact Type
name String Company Name
family_name String Family Name
given_name String Given Name
display_name Read-Only  String Display Name
title String Title
department String Department
format Read-Only    One of ['default', 'jp'] Name Format
phone_number String Phone Number
fax_number String Fax Number
is_default Read-Only  String Default Contact
email Email Address Email
addresses Array of Address Addresses
default_address Read-Only  HTML representation of Address Addresses
integrations Read-Only  JSON Object Relationship with external systems

Extra filters

These fields are also available to filter the list.

Fields Type Memo
search String Full text search

Document Archive


/api/partner/<partner_mid>/archive/
Document Archive List
GET OPTIONS
/api/partner/<partner_mid>/archive/<mid>/
Document Archive Instance
GET OPTIONS
/api/partner/<partner_mid>/archive/create/
Create and save a Document Archive
OPTIONS POST

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
  • send_to_clientinbox: sent by Send via Client Inbox 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.
Fields Type Description
mid Read-Only  MakeLeaps ID mid
url Read-Only  URL
pdf_content_url Read-Only  String
uses_external_pdf Read-Only  String
document_type   One of ['order', 'quote', 'orderslip', 'orderconfirmation', 'timesheet', 'deliveryslip', 'acceptance', 'invoice', 'receipt'] Document Type
document_number String Document Number
sending_methods Can have ['secure_send', 'send_to_clientinbox', 'japan_post', 'manually_sent_electronically', 'manually_sent_physically'] values. Choose one of ['manually_sent_electronically', 'manually_sent_physically'] when you create a Document Archive via the API. Sending Methods
legal_categories Read-Only  Array of ['electronically_from_makeleaps', 'physically_from_makeleaps', 'electronically_outside_makeleaps', 'physically_outside_makeleaps'] Legal Delivery Categories
date_sent   Timestamp Datetime that the Document Archive was created
date Date Issue Date of the Document archived
sender String
client String client
currency Currency
total Money Total
external_id String External ID

Sending Orders


/api/partner/<partner_mid>/sending/order/
Sending Order List
GET POST OPTIONS
/api/partner/<partner_mid>/sending/order/<mid>/
(No Name)
GET PUT PATCH DELETE OPTIONS

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>,
    "send_to_clientinbox_selected": true,
    "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",
        "send_to_clientinbox": "viewed",
        "sendbypost": "preparing",
        "securesend_cancelled": false,
        "send_to_clientinbox_cancelled": false,
        "sendbypost_cancelled": false
    },
}

General Options

Option(s) that affect all Sending Orders.

  • recipient_organization

Payment Options

Option(s) that only apply to processing of electronic sending methods where Clients can use MakeLeaps Payments (Secure Send and Send via Client Inbox).

  • enable_cc_payments

"Send via Client Inbox"-specific Options

  • send_to_clientinbox_selected

"Secure Send"-specific Options

  • securesend_selected
  • to_emails
  • subject
  • message

"Send by Post"-specific Options

  • 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>
}

Attaching a custom file

Files undergo validation when they are attached to a Sending Order, which can take some time depending on the file. Because of this, it is recommended to use async upload using Tasks.

Asynchronous uploads with Tasks (Recommended)

First, add the Sending Order Item.

POST <items_url>

Sample Data

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

Next, upload the custom file to the async_upload_url that is included in the POST's response.

PUT <async_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$--

The response to a PUT to async_upload_url will be a Task instance. For more on using Tasks, please see the Task section.

For asynchronous uploads of custom files, a GET of Task's result_url will return the corresponding Sending Order Item instance. (Same as a GET of the Sending Order Item's url)

A full list of Sending Order Item's asynchronous upload tasks can be obtained via a GET to the Item's async_upload_tasks_url.

Synchronous uploads without Tasks

The flow of synchronous uploads is basically the same as asynchronous, with the following 2 differences.

  • The upload is PUT to upload_url, not async_upload_url.
  • The response to the upload PUT is a Sending Order Item instance, not a Task.

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",
    "send_to_clientinbox": "viewed",
    "sendbypost": "preparing",
    "securesend_cancelled": false,
    "send_to_clientinbox_cancelled": false,
    "sendbypost_cancelled": false
}

Send via Client Inbox

Status is in send_to_clientinbox. Possible values are:

  • not_selected - "Send via Client Inbox" is/was not selected as a sending method on the Order.
  • draft - "Send via Client Inbox" selected but Order not yet executed.
  • not_viewed - "Send via Client Inbox" executed but not yet viewed.
  • cancelled - "Send via Client Inbox" executed but cancelled before it was viewed.
  • viewed - "Send via Client Inbox" executed and already seen by the client.

Secure Send

Status is in securesend. Possible values are:

  • not_selected - "Secure Send" is/was not selected as a sending method on the Order.
  • draft - "Secure Send" selected but Order not yet executed.
  • not_viewed - "Secure Send" executed but not yet viewed.
  • cancelled - "Secure Send" executed but cancelled before it was viewed.
  • viewed - "Secure Send" executed and already viewed.

Send by Post

Status is in sendbypost. Possible values are:

  • not_selected - "Send by Post" is/was not selected as a sending method on the Order.
  • draft - "Send by Post" selected but Order not yet executed.
  • can_cancel - "Send by Post" executed but can be cancelled.
  • cancelled - "Send by Post" executed but cancelled in 30-minute grace period. Nothing will be/was mailed.
  • preparing - "Send by Post" executed and cannot be cancelled. Currently being prepared for mailing.
  • mailed - "Send by Post" executed and the Order was mailed.
  • info_not_available - information about this order is unavailable.

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,
    "send_to_clientinbox_cancelled": true,
    "sendbypost_cancelled": false
}

Scheduling a Sending Order's execution

Set the date_scheduled field to schedule the execution of a Sending Order. MakeLeaps servers will execute the Order automatically after its date_scheduled has passed.

A Sending Order that has a non-null date_scheduled is called a "Scheduled Sending Order".

Notes:

  • date_scheduled should be specified in UTC (Z format). Do not forget to convert your desired datetime from your timezone to UTC.
  • date_scheduled must meet be both
    • after current server time, and
    • before midnight of the day 35 days after server's current UTC date.
  • Schedule Sending Orders are processed in twice hourly batches (:00 and :30). Because of this, Orders reserved for 00:05 will be run at 00:30. To avoid confusion, date_scheduled values of :00 or :30 are recommended.
  • date_scheduled needs to be specified to at least the minute.
  • Scheduled Sending Orders will no longer accept PATCH requests, only DELETE.
  • If date_scheduled is not specified in a request's data, its value will be assumed to be null and the Sending Order will be a draft. Draft orders need to be sent via a request to the send_url.

Sample PUT/PATCH data (this would send at 9am JST, Nov 11, 2023):

Sample data:

{
    ...
    "date_scheduled": "2023-11-11T00:00:00Z",
    ...
}

Discard a Scheduled Send

Since Scheduled Sending Orders cannot be altered, they must be deleted using a DELETE request and then recreated.

Fields Type Description
url Read-Only  URL
send_url Read-Only  URL
recipient_organization   Client URL (Expandable) Client
employee Read-Only    URL Employee URL
securesend_selected   Boolean Secure Send
to_emails Array of String Email Addresses
send_to_contacts Array of URL Contacts
subject String Subject
message String Message
enable_cc_payments Boolean Enable Credit Card Payments
sendbypost_selected   Boolean Japan Post
stamp_type One of ['invoice', 'quote', 'deliveryslip', 'orderslip', 'orderconfirmation', 'acceptance', 'receipt', 'nostamp', 'many_documents'] Envelope Stamp
ready_to_order Read-Only  Boolean
pdf_content_url Read-Only  URL
recipient_contact_organization_name String Client Name
recipient_contact_department String Department
recipient_contact_title String Title
recipient_contact_name String Contact Name
recipient_honorific String Recipient Honorific
recipient_address Address Address
sender_contact_organization_name String Sender Company Name
sender_contact_phone_number String Phone Number
sender_address Address Address
validation_errors Read-Only  String
items Read-Only  Array of Sending Order Item
items_url Read-Only  URL
status Read-Only  String Status
external_id String External ID
date_scheduled Timestamp date scheduled
send_to_clientinbox_selected   Boolean Send via Client Inbox

Extra filters

These fields are also available to filter the list.

Fields Type Memo
securesend_status String One of ['draft', 'not_selected', 'cancelled', 'viewed', 'not_viewed']
sendbypost_status String One of ['draft', 'not_selected', 'cancelled', 'can_cancel', 'preparing', 'mailed', 'info_not_available']
send_to_clientinbox_status String One of ['draft', 'not_selected', 'cancelled', 'viewed', 'not_viewed']

Sending Order Item


Fields Type Description
url Read-Only  URL
sending_order URL Sending Order URL
position Integer Position
document   URL Document URL
filename String File Name
upload_url Read-Only  URL
async_upload_url Read-Only  URL Custom file async upload URL
async_upload_tasks_url Read-Only  URL Custom file async upload task list URL

History


/api/partner/<partner_mid>/history/
History Entry List
GET POST OPTIONS
/api/partner/<partner_mid>/history/<mid>/
History Entry Instance
GET OPTIONS

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
Fields Type Description
mid Read-Only  MakeLeaps ID MakeLeaps ID
web_url Read-Only  URL URL
action_time Read-Only    Timestamp action time
created_by Read-Only    Employee Created By
event_name   String Event
metadata Read-Only  String Data
action_flag   Integer action flag
object_repr String object repr

Secure Inbox


/api/partner/<partner_mid>/inbox/inbox/
Secure Inbox
GET OPTIONS

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.
Fields Type Description
mid Read-Only  String MakeLeaps ID
url Read-Only  URL
type   One of ['received_doc', 'accepted_order', 'confirmed_doc'] Type
accepted_order Accepted Order Accepted Order
received_doc Received Document Received Document
time_received   Timestamp Time Received
time_read Timestamp Time Read

Extra filters

These fields are also available to filter the list.

Fields Type Memo
total_from Number
total_to Number
issued_date_from Date
issued_date_to Date
sender_name String
is_unconverted Boolean

Received Document


Fields Type Description
mid Read-Only  String MakeLeaps ID
url Read-Only  URL
document_data Visible Document Data Visible Document Data
vendor_name Read-Only  String Client Name
display_name Read-Only  String Display Name
pdf_content_url Read-Only  URL
generated_document_set Array of Document Generated Documents
received_by   URL Employee that added to Secure Inbox

Accepted Order


Fields Type Description
mid Read-Only  String MakeLeaps ID
url Read-Only  URL
time_accepted Timestamp Time Accepted
client Read-Only  Client
document   URL Document
document_data JSON Object Visible Document Data
is_paid Read-Only  Boolean Paid
signatory String Signer
note String Note
generated_document_set Read-Only  String Generated Documents
display_name Read-Only  String Display Name
document_was_edited Read-Only  Boolean Document was modified
pickup_authorization_mid Read-Only  String MakeLeaps ID
clientinbox_item_mid Read-Only  String MakeLeaps ID
date Read-Only  Date Date

Visible Document Data


Fields Type Description
document_number String Document Number
document_type One of ['order', 'quote', 'orderslip', 'orderconfirmation', 'timesheet', 'deliveryslip', 'acceptance', 'invoice', 'receipt'] Document Type
title String Title
project_name String Project
bank_details_header String Bank Details Header
bank_details String Bank Details
message String Message
proviso String Proviso
group_lineitem_by_tax_rate Boolean Group line items by tax rate
has_hanko Boolean Display Hanko on this document
has_prices Boolean Display prices on this document
has_totals Boolean Display totals on this document
has_currency_code Boolean Display the currency code on this document
has_lineitem_tax_state Boolean Show the tax state for each line item on this document
signature Boolean Show signature field
display_tax_rate Boolean Display document tax rate
hide_tax_description Boolean Hide alternate tax description
has_tax_stamp Boolean Show tax stamp
jp_withholding_tax_type One of ['original_reconstruction_tax', 'original'] Withholding Tax Type
currency Currency Currency
subtotal Money Subtotal
tax Money Tax
jp_withholding_tax Money Withholding Tax
tax_rate Number Tax Rate
subtotal_sales_tax Money Subtotal of the items Sales Tax is Applied
subtotal_withholding_tax Money Subtotal of the items Witholding Tax is Applied
total Money Total
mixed_tax_rate_totals JSON Object Totals with Mixed Tax Rates
extended_data JSON Object Extended Data
date Date Date
date_due Date Date Due
date_valid Date Valid Until
date_shipped Date Shipment Date
sender_name String Sender Name
sender_contact_department String Company Contact Department
sender_contact_title String Company Contact Title
sender_contact_name String Company Contact Name
sender_address_format String Company Address Format
sender_country String Company Country Name
sender_postal_code String Company Postal Code
sender_region String Company State
sender_locality String Company City
sender_street_address String Company Street Address
sender_extended_address String Company Extended Address
sender_phone_number String Company Phone Number
sender_fax_number String Company Fax Number
recipient_name String Client Name
recipient_contact_department String Client Contact Department
recipient_contact_title String Client Contact Title
recipient_contact_name String Client Contact
recipient_honorific String Recipient Honorific
recipient_address_format String Client Address Format
recipient_country String Client City
recipient_postal_code String Client Postal Code
recipient_region String Client State
recipient_locality String Client City
recipient_street_address String Client Street Address
recipient_extended_address String Client Extended Address
recipient_phone_number String Client Phone Number
recipient_fax_number String Client Fax Number
lineitems Array of Visible Line Item Data Line Items
purchase_order_ids Array of String PO Numbers
partner_tax_registration_number String Tax Registration Number

Document Pickup Link


/api/partner/<partner_mid>/document/<document_mid>/pickup-link/
Document Pickup Link List
GET POST OPTIONS
/api/partner/<partner_mid>/secureinbox/pickup-link/<mid>/
Document Pickup Link
GET OPTIONS
/api/partner/<partner_mid>/secureinbox/pickup-link/<mid>/cancel/
Cancel Document Pickup Link
POST OPTIONS
/api/partner/<partner_mid>/secureinbox/pickup-link/<mid>/uncancel/
Re-enable cancelled Document Pickup Link
POST OPTIONS

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/
Fields Type Description
mid Read-Only  MakeLeaps ID MakeLeaps ID
url Read-Only  URL
cancel_url Read-Only  URL
uncancel_url Read-Only  URL
created Read-Only  Timestamp Created
link Read-Only  URL Document Pickup Link
email String Email
date_clicked Timestamp Viewed
source Read-Only  String
expiration_date Timestamp Expiration date
is_cancelled Read-Only  Boolean Cancelled
created_by Read-Only  String Created by
supersend Read-Only  String Send Order
date_cancelled Read-Only  String

Task


/api/partner/<partner_mid>/task/<mid>/
Task Instance
GET OPTIONS
/api/partner/<partner_mid>/task/<mid>/results/
Result of a Task
OPTIONS GET

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
        }
    ]
}
Fields Type Description
mid Read-Only  MakeLeaps ID MakeLeaps ID
uilongtask Task Progress Task Progress
employee Read-Only    URL Employee URL
url Read-Only  URL
result_url Read-Only  URL
completion Read-Only  Integer Task Progress
failed_chunks Read-Only  Array of String Failed
finished Timestamp Completed

Task Progress


Fields Type Description
url Read-Only  URL
mid Read-Only  MakeLeaps ID MakeLeaps ID
current_progress Integer Current Progress
max_progress Integer Max Progress
time_done Timestamp Time done
finished Read-Only  Boolean Completed
errors Read-Only  String Errors

Approval Request


/api/partner/<partner_mid>/approval/request/
Approval Request List
GET OPTIONS

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.
Fields Type Description
requester Read-Only    URL Team Member Requesting Approval
document Read-Only    URL Document subject to Approval
status Read-Only    One of ['pending', 'rejected', 'approved', 'cancelled'] Request Status
date_completed Read-Only    Timestamp Datetime the Request was closed (either Approved or Rejected)

Virtual Accounts


/api/partner/<partner_mid>/virtual-account/destination-account/
Destination Bank Account List
GET OPTIONS
/api/partner/<partner_mid>/virtual-account/destination-account/<mid>/
Destination Bank Account Instance
GET OPTIONS

What is Virtual Accounts

"Virtual Accounts" is a feature that assigns unique virtual bank accounts to Clients.

Sets of Virtual Accounts redirect their deposits into a single real collection account, called a "Destination Account" in MakeLeaps. This endpoint returns the status of the Virtual Accounts associated with your Destination Account(s).

To use this feature, the "Virtual Accounts" option must be enabled in your subscription. If the option is not enabled, this endpoint will return a 404 error.

Fields Type Description
mid Read-Only  MakeLeaps ID mid
url Read-Only  URL
virtual_account_provider Read-Only  String Virtual account provider
purchased_virtual_account_count Read-Only  Integer Total virtual accounts purchased in current plan
used_virtual_account_count Read-Only  Integer Virtual accounts already assigned to Clients
available_virtual_account_count Read-Only  Integer Virtual accounts available for assignment to Clients

Notice regarding MakeLeaps API usage


  • 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.