- MakeLeaps REST API
- Authentication
- Money
- Supported Currencies
- Your Company
- Employees
- Documents
- Line Items
- Line Item Catalog
- Client Organizations
- Contacts
- Sending Orders
- Sending Order Item
- History
- Secure Inbox
- Received Document
- Accepted Order
- Visible Document Data
- Document Pickup Link
- Task
- Task Progress
- Notice regarding MakeLeaps API usage
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
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.
Filterable Fields
Certain resources have fields that are filterable. You can filter down the resources returned on the list view by that field with an extra query parameter.
For example, since the document_type
field of the Document resource is filterable, you can return a list
of all invoices by using the document_type
query parameter:
GET /api/partner/<partner_mid>/document/?document_type=invoice
The fields for which this is enabled is shown on the description of each resource's fields or extra filters table.
For filterable dates and timestamps on the Document resource, we also support range filtering. For example, the following
filters are available for the date
field:
# 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
Supported filters on 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, though 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)
Please contact us if there are any fields you would like to filter by that are not filterable yet.
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
These currencies are officially suported. Please contact support if a currency you would like to use is not yet supported.
Your Company
/api/partner/
/api/partner/<partner_mid>/
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 | |
---|---|---|
url | Read-Only | URL |
name | Read-Only | String |
clients | Read-Only | String |
contacts | Read-Only | String |
documents | Read-Only | String |
line_item_catalog | Read-Only | String |
tags | Read-Only | String |
sending_orders | Read-Only | String |
history | Read-Only | String |
integrations | Read-Only | JSON Object |
account_name | Read-Only | String |
Employees
/api/partner/<partner_mid>/employee/
/api/partner/<partner_mid>/employee/<mid>/
/api/partner/<partner_mid>/employee/me/
Employees represent the team members of your company.
Fields | Type | |
---|---|---|
url | Read-Only | URL |
mid | Read-Only | MakeLeaps ID |
name | Read-Only | String |
Read-Only | String | |
start_date | Read-Only | Timestamp |
end_date | Read-Only | Timestamp |
integrations | Read-Only | JSON Object |
has_seat | Read-Only | String |
is_owner | Read-Only | Boolean |
is_admin | Read-Only | String |
Extra filters
These filters are also available to filter the list.
Fields | Type | Memo |
---|---|---|
search | String | Full text search |
Documents
/api/partner/<partner_mid>/document/
/api/partner/<partner_mid>/document/<mid>/
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 ordersquote
for quotesorderslip
for order slipsorderconfirmation
for order confirmationsdeliveryslip
for delivery slipsacceptance
for acceptance certificatesinvoice
for invoicesreceipt
for receiptstimesheet
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_3",
"document_type": "invoice",
"display_name": "Professional (Japanese)",
"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 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
-
Quote:
date_sent
,date_cancelled
,date_paid
,date_accepted
-
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
-
Acceptance Certificate:
date_sent
,date_cancelled
,date_confirmed
-
Invoice:
date_sent
,date_cancelled
,date_paid
-
Receipts:
date_sent
,date_cancelled
Extra filters
These filters are also available to filter the list.
Fields | Type | Memo |
---|---|---|
client | MakeLeaps ID | |
client_contact | MakeLeaps ID | |
currency | String | |
tags | String | Accepts multiple tags separated by comma |
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 fieldssimple
for a line item that only has a description and an amount fieldtext
for a line item with only a description, and no money amountsubtotal
Whenautocalculate
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 Catalog
/api/partner/<partner_mid>/item/
/api/partner/<partner_mid>/item/<mid>/
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 ratealternate
: use the company alternate tax rate if it was set, otherwise the company default tax ratecustom
: use thetax_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.
Client Organizations
/api/partner/<partner_mid>/client/
/api/partner/<partner_mid>/client/<mid>/contact/
/api/partner/<partner_mid>/client/<mid>/
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 typeperson
.
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 anorganization
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 thesecure_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 thesecure_send_contacts
key.
(*) Note: the use_document_contact
setting does not affect who receives
documents that are sent via the API.
Extra filters
These filters are also available to filter the list.
Fields | Type | Memo |
---|---|---|
archived | Boolean | |
search | String | Full text search |
Contacts
/api/partner/<partner_mid>/contact/
/api/partner/<partner_mid>/contact/<mid>/
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.
Extra filters
These filters are also available to filter the list.
Fields | Type | Memo |
---|---|---|
search | String | Full text search |
Sending Orders
/api/partner/<partner_mid>/sending/order/
/api/partner/<partner_mid>/sending/order/<mid>/
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:
- Create a Sending Order with the desired options.
- Attach one or more Sending Order Items to the Sending Order.
- Wait for the system to validate the Sending Order to make sure it is sendable. Make any needed corrections if it isn't.
- 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
}
Extra filters
These filters 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'] |
Sending Order Item
History
/api/partner/<partner_mid>/history/
/api/partner/<partner_mid>/history/<mid>/
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
/api/partner/<partner_mid>/inbox/inbox/
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
andaccepted_order
types:accepted_order
field is populated andreceived_doc
is null.received_doc
type:received_doc
field is populated andaccepted_order
is null.
Extra filters
These filters 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
Accepted Order
Visible Document Data
Fields | Type | |
---|---|---|
document_number | String | |
document_type | One of ['order', 'quote', 'orderslip', 'orderconfirmation', 'timesheet', 'deliveryslip', 'acceptance', 'invoice', 'receipt'] | |
title | String | |
project_name | String | |
bank_details_header | String | |
bank_details | String | |
message | String | |
proviso | String | |
group_lineitem_by_tax_rate | Boolean | |
has_hanko | Boolean | |
has_prices | Boolean | |
has_totals | Boolean | |
has_currency_code | Boolean | |
has_lineitem_tax_state | Boolean | |
signature | Boolean | |
display_tax_rate | Boolean | |
hide_tax_description | Boolean | |
has_tax_stamp | Boolean | |
jp_withholding_tax_type | One of ['original_reconstruction_tax', 'original'] | |
currency | Currency | |
subtotal | Money | |
tax | Money | |
jp_withholding_tax | Money | |
tax_rate | Number | |
subtotal_sales_tax | Money | |
subtotal_withholding_tax | Money | |
total | Money | |
mixed_tax_rate_totals | JSON Object | |
extended_data | (Unknown) | |
date | Date | |
date_due | Date | |
date_valid | Date | |
date_shipped | Date | |
sender_name | String | |
sender_contact_department | String | |
sender_contact_title | String | |
sender_contact_name | String | |
sender_address_format | String | |
sender_country | String | |
sender_postal_code | String | |
sender_region | String | |
sender_locality | String | |
sender_street_address | String | |
sender_extended_address | String | |
sender_phone_number | String | |
sender_fax_number | String | |
recipient_name | String | |
recipient_contact_department | String | |
recipient_contact_title | String | |
recipient_contact_name | String | |
recipient_honorific | String | |
recipient_address_format | String | |
recipient_country | String | |
recipient_postal_code | String | |
recipient_region | String | |
recipient_locality | String | |
recipient_street_address | String | |
recipient_extended_address | String | |
recipient_phone_number | String | |
recipient_fax_number | String | |
lineitems | Array of Visible Line Item Data | |
purchase_order_ids | Array of String | |
partner_tax_registration_number | String |
Document Pickup Link
/api/partner/<partner_mid>/document/<document_mid>/pickup-link/
/api/partner/<partner_mid>/secureinbox/pickup-link/<mid>/
/api/partner/<partner_mid>/secureinbox/pickup-link/<mid>/cancel/
/api/partner/<partner_mid>/secureinbox/pickup-link/<mid>/uncancel/
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 | |
---|---|---|
mid | Read-Only | MakeLeaps ID |
url | Read-Only | URL |
cancel_url | Read-Only | URL |
uncancel_url | Read-Only | URL |
created | Read-Only | Timestamp |
link | Read-Only | String |
String | ||
date_clicked | Timestamp | |
source | Read-Only | String |
expiration_date | Timestamp | |
is_cancelled | Read-Only | String |
created_by | Read-Only | String |
supersend | Read-Only | String |
Task
/api/partner/<partner_mid>/task/<mid>/
/api/partner/<partner_mid>/task/<mid>/results/
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
}
]
}
Task Progress
Fields | Type | |
---|---|---|
url | Read-Only | URL |
mid | Read-Only | MakeLeaps ID |
current_progress | Integer | |
max_progress | Integer | |
time_done | Timestamp | |
finished | Read-Only | String |
errors | Read-Only | String |
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.