MakeLeaps REST API


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

For more information about this system, please contact support@makeleaps.com

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

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 the following endpoints :

  • Document List
  • Client List

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.

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

Here are the following supported filters on dates and timestamps, usable by appending to the field name:

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

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
GET 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
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

Employees


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

Employees represent the team members of your company.

Fields Type
url Read-Only  URL
mid Read-Only  MakeLeaps ID
name Read-Only  String
email 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

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

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

Fields Type
mid Read-Only  MakeLeaps ID
document_number   String
document_type   Document Type
document_template   Document Template
display_name Read-Only  String
title String
project_name String
bank_details_header String
bank_details String
message String
proviso String
note String
external_id   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
currency   Currency
round_tax_down Boolean
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 (Unknown)
tags Array of Tag
url Read-Only  URL
pdf_content_url Read-Only  String
client     Client URL (Expandable)
client_contact     Contact URL
date   Date
date_due   Date
date_paid   Timestamp
date_sent   Timestamp
date_valid   Date
date_cancelled   Timestamp
date_shipped   Date
date_removed Read-Only    Timestamp
date_accepted   Timestamp
date_confirmed   Timestamp
date_converted Read-Only    Timestamp
is_accepted Read-Only  String
is_confirmed Read-Only  String
is_converted Read-Only  String
approval_status Read-Only  One of ['approved', 'rejected']
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 Line Item
integrations Read-Only  JSON Object
autocalculate Boolean
use_virtual_account 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

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.

Fields Type
kind Line Item Type
description String
unit_cost Money
quantity Number
quantity_unit String
price Money
is_taxable Boolean
is_tax_inclusive Boolean
has_jp_withholding_tax Boolean
vendor_cost Money
currency Currency
source_catalog_item   Catalog Item URL
tax_rate Number

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.

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
kind Line Item Type
description String
unit_cost Money
quantity Number
quantity_unit String
price Money
is_taxable Boolean
is_tax_inclusive Boolean
has_jp_withholding_tax Boolean
vendor_cost Money
currency Currency
tax_rate Number
mid Read-Only  MakeLeaps ID
url Read-Only  URL
product_code   String
interval One of ['monthly', 'bimonthly', 'quarterly', 'yearly']
metered Boolean
tax_category One of ['default', 'alternate', 'custom']

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 }/"
}''

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 }/"
}''

The MakeLeaps Payments feature should be enabled for your company to be able to set enable_cc_payments to true.

The use_document_contact setting for a client determines which contacts are selected to be sent to when users select to send a document in the UI. If use_document_contact is set to false, then the contacts in the secure_send_contacts are used.

If use_document_contact is set to true, no secure_send_contacts should be provided.

Fields Type
url Read-Only  URL
mid Read-Only  MakeLeaps ID
display_name Read-Only  String
organization_type Read-Only  String
is_organization Read-Only  String
date_archived Read-Only  Timestamp
client_external_id   String
contacts Array of Contact URL
default_contact   Contact URL
managing_teams Read-Only  Array of Group
default_presets Read-Only    Array of Preset URL (Expandable)
integrations Read-Only  JSON Object
lang_code String
settings Read-Only  String

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.

Fields Type
url Read-Only  URL
mid Read-Only  String
owner Read-Only  (Unknown)
owner_type Read-Only    String
contact_type   One of ['organization', 'person']
name String
family_name String
given_name String
display_name Read-Only  String
title String
department String
format Read-Only    One of ['default', 'jp']
phone_number String
fax_number String
is_default Read-Only  String
email Email Address
addresses Array of Address
default_address Read-Only  HTML representation of Address
integrations Read-Only  JSON Object

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 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>,
    "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"
    }
}

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.

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

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
}
Fields Type
url Read-Only  URL
send_url Read-Only  String
recipient_organization   Client URL (Expandable)
employee Read-Only    Employee URL
securesend_selected Boolean
to_emails (Unknown)
send_to_contacts Array of Contact URL
subject String
message String
enable_cc_payments Boolean
sendbypost_selected Boolean
stamp_type One of ['invoice', 'quote', 'deliveryslip', 'orderslip', 'orderconfirmation', 'acceptance', 'nostamp', 'many_documents']
ready_to_order Read-Only  String
pdf_content_url Read-Only  String
recipient_contact_organization_name String
recipient_contact_department String
recipient_contact_title String
recipient_contact_name String
recipient_honorific String
recipient_address (Unknown)
sender_contact_organization_name String
sender_contact_phone_number String
sender_address (Unknown)
validation_errors Read-Only  String
items Read-Only  Array of (Unknown)
items_url Read-Only  String
status Read-Only  String
external_id String

Sending Order Item


Fields Type
url Read-Only  URL
sending_order Sending Order URL
position Integer
document   Document URL
filename String
upload_url Read-Only  String

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
mid Read-Only  MakeLeaps ID
web_url Read-Only  String
action_time Read-Only    Timestamp
created_by Read-Only    Employee
event_name   String
metadata Read-Only  String
action_flag   Integer
object_repr String