Your API key

Create one in the portal under API keys.

Browse the API

API reference

Assignment rules

Decide which template applies to which people, by department, domain or person.

4 endpoints

GET/api/v1/rules

List rules

Every assignment rule, highest priority first, with the template and the target it resolves to.

rules:read

This endpoint takes no parameters beyond the URL itself.

Example response

json

{
  "rules": [
    {
      "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
      "name": "Sales team",
      "priority": 10,
      "template_id": "b8e0f1a2-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
      "template_name": "Standard",
      "scope_type": "department",
      "scope_value": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "scope_label": "Sales",
      "condition_type": null,
      "condition_value": null,
      "compose_type": "all",
      "recipient_type": "external",
      "starts_at": null,
      "ends_at": null,
      "active": true
    }
  ],
  "total": 2
}

Copy and paste

curl -X GET "https://api.usesigned.co.uk/api/v1/rules" \
  -H "X-API-Key: $SIGNED_API_KEY"

POST/api/v1/rules

Create a rule

Adds an assignment rule. The highest priority rule that matches a person wins.

rules:writeplan feature: rules

Parameters

JSON body

nameRequired
stringRule name.
up to 255 characters
example: "Sales team"
template_idRequired
stringTemplate to use when the rule matches.
uuid
scope_typeRequired
one ofWho the rule applies to.
one of: all, department, user, email_domain · default "all"
scope_valueOptional
stringThe department ID, user ID or domain. Omit when scope_type is all.
up to 255 characters
example: "acme.com"
priorityOptional
numberHigher wins. Rules with no priority sit at 0.
default 0
condition_typeOptional
stringReserved for conditional rules. Leave null.
up to 50 characters
condition_valueOptional
stringReserved for conditional rules. Leave null.
up to 255 characters
compose_typeOptional
one ofOnly match new emails, or only replies and forwards.
one of: all, new, reply · default "all"
recipient_typeOptional
one ofOnly match when someone outside the organisation is on the email, or when everyone is inside it.
one of: all, external, internal · default "all"
starts_atOptional
dateFirst day the rule applies, as YYYY-MM-DD, in the organisation’s time zone.
YYYY-MM-DD
ends_atOptional
dateLast day the rule applies, as YYYY-MM-DD. It runs to the end of that day.
YYYY-MM-DD
activeOptional
booleanTurn the rule off without deleting it.
default true

Example request body

json

{
  "name": "Sales team",
  "template_id": "b8e0f1a2-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
  "scope_type": "department",
  "scope_value": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "priority": 10,
  "recipient_type": "external"
}

Example response

json

{
  "rule": {
    "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
    "name": "Sales team",
    "priority": 10,
    "active": true
  }
}

Copy and paste

curl -X POST "https://api.usesigned.co.uk/api/v1/rules" \
  -H "X-API-Key: $SIGNED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales team","template_id": "b8e0f1a2-3c4d-4e5f-8a9b-0c1d2e3f4a5b","scope_type": "department","scope_value": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","priority": 10,"recipient_type": "external"}'

Worth knowing

The template, department and user IDs are all checked against your organisation before anything is written.

PATCH/api/v1/rules/{id}

Update a rule

Updates a rule. Send only the fields you want to change.

rules:writeplan feature: rules

Parameters

In the path

idRequired
stringRule ID.
uuid

JSON body

nameOptional
stringRule name.
up to 255 characters
template_idOptional
stringTemplate to use when the rule matches.
uuid
scope_typeOptional
one ofWho the rule applies to.
one of: all, department, user, email_domain
scope_valueOptional
stringThe department ID, user ID or domain.
up to 255 characters
priorityOptional
numberHigher wins.
compose_typeOptional
one ofOnly match new emails, or only replies and forwards.
one of: all, new, reply
recipient_typeOptional
one ofOnly match external or internal emails.
one of: all, external, internal
starts_atOptional
dateFirst day the rule applies, as YYYY-MM-DD. Send null to remove.
YYYY-MM-DD
ends_atOptional
dateLast day the rule applies, as YYYY-MM-DD. Send null to remove.
YYYY-MM-DD
activeOptional
booleanTurn the rule off without deleting it.

Example request body

json

{
  "active": false
}

Example response

json

{
  "rule": {
    "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
    "active": false
  }
}

Copy and paste

curl -X PATCH "https://api.usesigned.co.uk/api/v1/rules/{id}" \
  -H "X-API-Key: $SIGNED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

DELETE/api/v1/rules/{id}

Delete a rule

Deletes a rule. Anyone it matched falls through to the next matching rule, or the default template.

rules:write

Parameters

In the path

idRequired
stringRule ID.
uuid

Example response

json

{
  "deleted": true
}

Copy and paste

curl -X DELETE "https://api.usesigned.co.uk/api/v1/rules/{id}" \
  -H "X-API-Key: $SIGNED_API_KEY"