Make API
The Make API allows you to generate a new PDF or image from an imported Make template.
Not sure how to make a template? Check out this handy guide.
Sync Method
In most cases the Make API can be called synchronously to return a result in 30 seconds.
Endpoint
https://api.make.cm/make/t/:template-id/sync
If you wish to generate time-consuming templates and need more than 30 seconds, please read the Async method.
Headers & Authorization
Param | Type | Notes |
---|---|---|
Content-Type (required) | application/json | The content type should always be JSON |
X-MAKE-API-KEY (required) | string | A Make API Key must be sent with the POST request. A key can be generated from the template dashboard or on the Team Settings page. |
Request Structure
const apiUrl = 'https://api.make.cm/make/t/:id/sync'const { body } = await fetch(apiUrl, {method: 'POST',headers: {'Content-Type': 'application/json','X-MAKE-API-KEY': '[API KEY]'},body: {"size": "A4","format": "pdf","data": {"headline": "Hello World"},"postProcessing": {"optimize": false}}}).then(res => res.json())
Response
{"resultUrl": "https://exports.make.cm/....",}
{"0": {"target": {"size": "A14","format": "pdf","data": {"headline": "Hello World"}},"value": "A14","property": "size","children": [],"constraints": {"isEnum": "size must be a valid enum value"}},"statusCode": 400}
Async Method
In some cases template generations may take longer than 30 seconds (which is the timeout limit for the sync Make Asset endpoint). In these events you can use the asynchronous Make Asset call.
Request processing will run in the background and will be delivered to the webhookUrl
(specified in the initial request). Or you can call the Status API to check the status at anytime.
Endpoint
https://api.make.cm/make/t/:template-id/async
Headers & Authorization
Param | Type | Notes |
---|---|---|
Content-Type (required) | application/json | The content type should always be JSON |
X-MAKE-API-KEY (required) | string | A Make API Key must be sent with the POST request. A key can be generated from the template dashboard or on the Team Settings page. |
Request Structure
const apiUrl = 'https://api.make.cm/make/t/:id/async'const { body } = await fetch(apiUrl, {method: 'POST',headers: {'Content-Type': 'application/json','X-MAKE-API-KEY': '[API KEY]'},body: {"size": "A4","format": "pdf","webhookUrl": "https://...","webhookState": "CustomWebhookState","data": {"headline": "Hello World"},"postProcessing": {"optimize": false}}}).then(res => res.json())
Response
{"requestId": "93a370af-52ac-48e0-990a-af4a23ec56d2","templateId": "94a16a59-fcde-45aa-b999-218b960d51fb","statusUrl": "https://api.make.cm/make/t/94a16a59-fcde-45aa-b999-218b960d51fb/r/93a370af-52ac-48e0-990a-af4a23ec56d2"}
{"0": {"target": {"size": "A14","format": "pdf","data": {"headline": "Hello World"}},"value": "A14","property": "size","children": [],"constraints": {"isEnum": "size must be a valid enum value"}},"statusCode": 400}
Webhook
If you have specified the webhookUrl
and webhookState
in your request, upon finalization of the request, Make will perform a POST
request to the specified webhookUrl
.
Your webhook handler must:
- Accept a POST request containing JSON data in the request body.
- Return a response within 5 seconds, otherwise Make will time out the request.
- Return a response with a 200 or 2xx status code to indicate that the webhook has been processed.
This is an example of what you will receive via your webhook from a successful result.
{"state": "ThisIsYourSpecifiedWebHookState","resultUrl": "https://exports.make.cm/","requestId": "c421311a-5eb2-4480-9176-aef9e6152a6f","status": "succeeded","logs": [{"timestamp": 1609300378812,"message": "Start rendering for request c421311a-5eb2-4480-9176-aef9e6152a6f"},{"timestamp": 1609300380719,"message": "Passing template data to template {\"headline\":\"Headline\"}"},{"timestamp": 1609300380856,"message": "DOMContentLoaded in 137ms"},{"timestamp": 1609300381365,"message": "Page finished in 646ms"},{"timestamp": 1609300381438,"message": "Uploading result..."},{"timestamp": 1609300381548,"message": "Result uploaded in 110ms"}]}
Dynamic Method
You can also generate assets using a GET
request instead of a POST
request so you can send / share the URL easier.
Endpoint
https://api.make.cm/make/t/:template-id/k/:generated-hmac-key/sync
If you want to render time-consuming templates and need more than 30 seconds, please read Make an Asset Asynchronously
Authorization
For each template a unique :generated-hmac
will be created, instead of using MAKE-API-KEY
's (used for POST Make Asset requests) so that when sharing the GET URL no API key is compromised.
The :generated-hmac
was created to allow for easy and secure sharing via URL, without the need for authorization headers and without the risk of compromising secret API keys.
In the Make app, click on a template and switch the API playground from POST - SYNC to GET - SYNC. The HMAC key will be available in the url.
Request Structure
GET https://api.make.cm/make/t/:template-id/k/:generated-hmac/sync?size=A4&format=png&data[headline]=Hello World
Response
https://exports.make.cm/....
{"0": {"target": {"size": "A14","format": "pdf","data": {"headline": "Hello World"}},"value": "A14","property": "size","children": [],"constraints": {"isEnum": "size must be a valid enum value"}},"statusCode": 400}
Parameters
All methods (Sync, Async and Dynamic) share the same parameters. The body of the request is made up of 5 key groups of parameters.
size
orcustomSize
you want the asset to be. (required)format
of the generated asset. (required)data
you want to send to the template before generating the asset.postProcessing
options on the generated asset.
There are also a range of other parameters available as well.
size & customSize
The size of the asset can be determined by either the size
paramater which accepts a string
or a customSize
which you can define a custom object of width
, height
and unit
.
"size": "A4","customSize": {"width": 1000,"height": 500,"unit": "px"}
&size=A4&customSize[width]=1000&customSize[height]=500&customSize[unit]=px
Param | Type | Notes |
---|---|---|
size (required) | string | Supported sizes:
|
customSize (required) | object | width : number height : number unit : string Unit options:
unit is case sensitive and should be written in lowercase. |
format
The format
specifies what the template will be generated into. Depending on the format type, generation times may vary.
"format": "PDF"
&format=pdf
Param | Type | Notes |
---|---|---|
format (required) | string | format is case sensitive and should be written in lowercase.Supported formats:
|
postProcessing
Based on the format
there are available a range of post processing parameters that can be used to augment the generated asset.
"postProcessing": {"optimize": true,"targetDPI": 72}
&postProcessing[optimize]=true&postProcessing[targetDPI]=72
Param | Type | Format | Notes |
---|---|---|---|
optimize | boolean | PDF PNG JPG | Optimization may create a longer generation time. For PDF , by default raster elements will be optimized to 72 DPI.Default: true |
targetDPI | number | PDF | Determines a custom the optimization ceiling for raster elements. For print documents it is suggested to use 300 Options:
Default: 72 The optimize parameter must be set to true for this to apply. |
colorSpace | string | PDF | Will convert all PDF objects to the chosen color space. Options:
Default: rgb colorSpace is case sensitive and should be written in lowercase. |
colorProfile | string | PDF | Determines the CMYK color profile. Default is USWebCoatedSWOP .See here for a full list of available color profiles. |
colorMapping | array | PDF | Specify an RGB color to map to a specific CMYK or spot separation color. This will not apply to raster elements. See here for a full guide on color mapping. |
cropBox | string | PDF | Defines the region that the PDF viewer is expected to display or print. Default: (0, 0, 0, 0) |
trimBox | string | PDF | Defines the intended dimensions for print. Default: (0, 0, 0, 0) |
Learn more about crop and trim boxes here
data
The data
object allows you to send custom data to the window of the imported template. Have a look here to see how you can prep your template to accept custom data.
"data": {"headline": "Hello World","list": ["Item1","Item2"]}
&data[headline]=Hello&data[list][]=Item1&data[list][]=Item2
Param | Type | Notes |
---|---|---|
data | JSON | Send any custom data to the template. |
Other Optional Parameters
"fileName": "custom-file-name","contentDisposition": "attachment"
&fileName=custom-file-name&contentDisposition=attachment
Param | Type | Notes |
---|---|---|
fileName | string | Provide the newly generated asset with a custom filename. By default a UUID name will be generated.fileName can only include the following characters:
The extension should not be included in the fileName . |
contentDisposition | string | Determines the way in which the asset will be returned to your application. Options:
Default: inline |
expiresAt | string | Can set a custom expiry for the asset. Supplied as an ISO date and time string. eg. 2021-11-13T20:20:39+00:00 Default: generated timestamp, valid for 12 hours |
allowTransparency | boolean | Specifies if the png output will support transparency. This option is only available to png format.Default: false (will include a white background)format must be png for this to work. |
draftWatermarkUrl | string | Will accept a public url of an image asset and overlay that over the generated artwork on generation. |
webhookUrl (optional) (async only) | string | The URL to the webhook that listens to POST requests. |
webhookState (optional) (async only) | string | The secret string shared with the webhook that allows Make to POST results to the webhook. It is suggested that the webhookState is at least 20 characters long and includes an array of numbers, letters and characters. |