Skip to content
Last updated

Manage templates

Use these endpoints to create new templates and add language variants to existing ones.
Before making requests, ensure you have configured authentication.

For the full technical reference, see the OpenAPI specification.


Create a template

Creates a new template. The template will be submitted to Meta for approval and will have status PENDING until approved.

Endpoint

POST /api/template/create

Headers

NameRequiredDescription
AuthorizationYesBasic Auth credentials. See Authentication.
X-Api-KeyYesAPI key for the account. See Authentication.
Content-TypeYesMust be application/json.

Body parameters

ParameterTypeRequiredDescription
languagestringYesDefault template language. See supported languages
categorystringYesTemplate category: UTILITY or MARKETING
namestringYesTemplate name. Only alphabetic characters and underscores (max 100 characters)
descriptionstringYesTemplate description
bodyobjectYesBody text with optional placeholders ({{1}}, {{2}}, ...) and default parameter values
urlButtonsarrayDependsURL buttons. Each entry: index, text (button label), url (base URL with optional {{1}} placeholder), urlPath (default path). Max 2 buttons.
textHeaderobjectNoHeader text (preset, no placeholders)
footerobjectNoFooter text (preset, no placeholders)
Template variable rules

Common rejection reasons from Meta:

  • Variable parameters must use the format {{1}}, {{2}}, etc.
  • Parameters cannot contain special characters like #, $, or %
  • Parameters must be sequential — no gaps (e.g. {{1}}, {{2}}, {{4}} without {{3}} is invalid)
  • Templates cannot start or end with a variable parameter
  • Too many parameters relative to message length

Request example

{
  "body": {
    "text": "Hello *{{1}}*, your signature is required for a document. Open by using following link:",
    "parameters": [
      { "text": "John Smith" }
    ]
  },
  "urlButtons": [
    {
      "index": 0,
      "urlPath": "sign",
      "url": "https://yourendpoint.com/{{1}}",
      "text": "Open Document"
    }
  ],
  "textHeader": {
    "text": "Document signing request"
  },
  "footer": {
    "text": "The link expires in 10 minutes"
  },
  "language": "en",
  "name": "signature_template",
  "category": "UTILITY",
  "description": "sign a doc using a link"
}

Response examples

200 — Template created (pending approval)

{
  "body": {
    "text": "Hello *{{1}}*, your signature is required for a document. Open by using following link:",
    "parameters": [
      { "text": "John Smith" }
    ]
  },
  "urlButtons": [
    {
      "index": 0,
      "urlPath": "sign",
      "url": "https://yourendpoint.com/{{1}}",
      "text": "Open Document"
    }
  ],
  "textHeader": {
    "text": "Document signing request"
  },
  "footer": {
    "text": "The link expires in 10 minutes"
  },
  "language": "en",
  "status": "PENDING",
  "category": "UTILITY",
  "name": "signature_template",
  "description": "sign a doc using a link",
  "templateId": "802",
  "default": true
}

The response returns the full template object. See Get template by language for a description of the response fields.

400 — Invalid input

{
  "type": "ConstraintViolationException",
  "code": 3,
  "message": "Allowed category are: UTILITY, MARKETING"
}

Error codes

HTTP StatusError codeError typeSolution
4003ConstraintViolationExceptionCheck the request parameters against the API documentation

For authentication errors (code 1, 6, 9), see Authentication.


Add a template language

Adds a new language version to an existing template.

Endpoint

POST /api/template/{templateId}/language

Headers

NameRequiredDescription
AuthorizationYesBasic Auth credentials. See Authentication.
X-Api-KeyYesAPI key for the account. See Authentication.
Content-TypeYesMust be application/json.

Path parameters

ParameterTypeRequiredDescription
templateIdintegerYesThe existing template ID

Body parameters

ParameterTypeRequiredDescription
languagestringYesThe new language to add. See supported languages
bodyobjectYesBody text in the new language with optional placeholders and default parameter values
urlButtonsarrayNoURL buttons for the new language version
textHeaderobjectNoHeader text in the new language
footerobjectNoFooter text in the new language

Request example

{
  "body": {
    "text": "Ciao *{{1}}*, la tua firma è richiesta per un documento. Aprilo usando il seguente link:",
    "parameters": [
      { "text": "Mario Rossi" }
    ]
  },
  "urlButtons": [
    {
      "index": 0,
      "urlPath": "sign",
      "url": "https://yourendpoint.com/{{1}}",
      "text": "Apri documento"
    }
  ],
  "textHeader": {
    "text": "Richiesta di firma documento"
  },
  "footer": {
    "text": "Il link scade in 10 minuti"
  },
  "language": "it"
}

Response examples

200 — Language added

{
  "body": {
    "text": "Ciao *{{1}}*, la tua firma è richiesta per un documento. Aprilo usando il seguente link:",
    "parameters": [
      { "text": "Mario Rossi" }
    ]
  },
  "urlButtons": [
    {
      "index": 0,
      "urlPath": "sign",
      "url": "https://yourendpoint.com/{{1}}",
      "text": "Apri documento"
    }
  ],
  "textHeader": {
    "text": "Richiesta di firma documento"
  },
  "footer": {
    "text": "Il link scade in 10 minuti"
  },
  "language": "it",
  "status": "PENDING",
  "category": "UTILITY",
  "name": "signature_template",
  "description": "sign a doc using a link",
  "templateId": "802",
  "default": false
}

The response returns the full template object for the new language variant. See Get template by language for a description of the response fields.

400 — Language already exists

{
  "type": "InvalidLanguageException",
  "code": 14,
  "message": "The language 'en' already exists for template '61'"
}

400 — Language not supported

{
  "type": "ClientWebApplicationException",
  "code": 12,
  "message": "Invalid parameter"
}

404 — Template not found

{
  "type": "UnavailableTemplateException",
  "code": 7,
  "message": "Template not found"
}

Error codes

HTTP StatusError codeError typeSolution
40012ClientWebApplicationExceptionThe language code is not supported by Meta. See supported languages
40014InvalidLanguageExceptionThe language already exists for this template
4047UnavailableTemplateExceptionVerify that the templateId exists

For authentication errors (code 1, 6, 9), see Authentication.