Render image

This endpoint allows you to generate images based on a template created in Template Editor.

POST Endpoint

https://get.renderform.io/api/v1/render

Sample request

curl 
    --location 
    --request POST 'https://get.renderform.io/api/v1/render' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "template": "<TEMPLATE_ID>",
        "changes": [
            {
              "id": "my-text-component-id",
              "color": "#eeeeee",
              "text": "Hello There!",
            },
            {
              "id": "my-image-component-id",
              "src": "https://jpomykala.com/assets/me-2019.jpeg"
            }
        ]
    }'

Request body

• template (required) - template identifier,
• changes (optional) - override component properties for given template,
• changesDictionary (optional) - override component properties for given template,
• expires (optional) - link expiration time in seconds, available values from 1 to 604800
• fileName (optional) - custom file name for generated image,
• webhookUrl (optional) - send response to the given URL as a POST request,
• metadata (optional) - any JSON object, can be used as metadata container.

Successful response

{
  "requestId": "febbd34c-cadf-43e6-926c-5942016aea4e",
  "href": "https://cdn.renderform.io/.../febbd34c-cadf-43e6-926c-5942016aea4e.jpg"
}

Sample request with metadata

Metadata field allows you to store any JSON object with the generated image.

curl 
    --location 
    --request POST 'https://get.renderform.io/api/v1/render' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "template": "<TEMPLATE_ID>",
        "changes": [
            {
              "id": "my-text-component-id",
              "color": "#eeeeee",
              "text": "Hello There!",
            },
            {
              "id": "my-image-component-id",
              "src": "https://jpomykala.com/assets/me-2019.jpeg"
            }
        ],
        "metadata": {
            "userId": "12345",
            "userName": "John Doe",
            "my-custom-key": "Hello World!"
        }
    }'

Other possibilities to provide template changes

In some cases providing template changes in the format specified above might not be easy to manage in your code. That is why we provide additional 2 formats to provide template changes.

Simple Array

Changes in changes request body field must be formatted as array and options query parameter must contain USE_SIMPLE_ARRAY value.

Every object of changes field must contain:

• id - component id set it template editor,
• property - component property (eg: text),
• value - component property value

curl 
    --location 
    --request POST 'https://get.renderform.io/api/api/v1/render?options=USE_SIMPLE_ARRAY' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "template": "<TEMPLATE_ID>",
        "changes": [
            {
                "id": "my-text-component-id",
                "property": "text",
                "value": "This is my text"
            },
            {
                "id": "my-image-component-id",
                "property": "src",
                "value": "https://my-website.com/image.jpg"
            }
        ]
    }'

Dictionary

Changes in changesDictionary request body field must be formatted as key-value object.

curl 
    --location 
    --request POST 'https://get.renderform.io/api/api/v1/render' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "template": "<TEMPLATE_ID>",
        "changesDictionary": {
          "my-text-component-id.text": "This is my text", 
          "my-image-component-id.src": "https://my-website.com/image.jpg" 
        }
    }'

Please note that in dictionary format, your component id cannot contain a dot . because RenderForm won't be able to process your request correctly.

GET Endpoint

https://get.renderform.io/img/TEMPLATE_ID.jpg?componentId.property=value&apiKey=API_KEY

Use Query String notation in order to provide changes.

Sample request

https://get.renderform.io/img/MY_TEMPLATE_ID.jpg?title.text=Hello!&avatar.src=example.com/me.jpg&apiKey=MY_API_KEY

Please note that only the first change element is separated with ? (question mark) and all other changes must be separated with & (ampersand).