Your API key

Create one in the portal under API keys.

Browse the API

API reference

People

Your directory. Create, update and import the people signatures are built for.

7 endpoints

GET/api/v1/users

List people

Lists the directory, newest page first, ordered by display name.

users:read

Parameters

Query string

searchOptional
stringMatches display name, email or job title.
example: "alex"
department_idOptional
stringLimit to one department.
uuid
statusOptional
one ofLimit by whether the person is active.
one of: active, inactive
pageOptional
numberPage number, starting at 1.
default 1 · min 1
limitOptional
numberHow many to return per page.
default 50 · min 1 · max 500

Example response

json

{
  "users": [
    {
      "id": "7c3f2b1a-0d4e-4f5a-8b9c-1d2e3f4a5b6c",
      "email": "alex.morgan@acme.com",
      "display_name": "Alex Morgan",
      "first_name": "Alex",
      "last_name": "Morgan",
      "job_title": "Operations Manager",
      "department_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "department_name": "Operations",
      "phone": "+44 20 7946 0000",
      "mobile": null,
      "active": true
    }
  ],
  "total": 68,
  "page": 1,
  "limit": 50
}

Copy and paste

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

POST/api/v1/users

Create a person

Adds someone to the directory. Only the email address is required; the display name falls back to the email.

users:write

Parameters

JSON body

emailRequired
stringEmail address. Unique within the organisation.
up to 255 characters · email
display_nameOptional
stringName shown in signatures.
up to 255 characters
first_nameOptional
stringFirst name.
up to 255 characters
last_nameOptional
stringLast name.
up to 255 characters
job_titleOptional
stringJob title.
up to 255 characters
department_idOptional
stringDepartment to place them in.
uuid
phoneOptional
stringLandline or office number.
up to 100 characters
mobileOptional
stringMobile number.
up to 100 characters
companyOptional
stringOverrides the company default.
up to 255 characters
websiteOptional
stringOverrides the website default.
up to 255 characters
addressOptional
stringOverrides the address default.
up to 2000 characters
linkedinOptional
stringLinkedIn URL or handle.
up to 255 characters
twitterOptional
stringX, formerly Twitter, URL or handle.
up to 255 characters
photo_urlOptional
stringPublic URL of their photo.
up to 2000 characters
custom_fieldsOptional
objectExtra values, available to templates by key.
activeOptional
booleanSet false to add someone without issuing a signature.
default true

Example request body

json

{
  "email": "alex.morgan@acme.com",
  "first_name": "Alex",
  "last_name": "Morgan",
  "job_title": "Operations Manager",
  "mobile": "+44 7700 900000",
  "custom_fields": {
    "extension": "412"
  }
}

Example response

json

{
  "user": {
    "id": "7c3f2b1a-0d4e-4f5a-8b9c-1d2e3f4a5b6c",
    "email": "alex.morgan@acme.com",
    "display_name": "Alex Morgan"
  }
}

Copy and paste

curl -X POST "https://api.usesigned.co.uk/api/v1/users" \
  -H "X-API-Key: $SIGNED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "alex.morgan@acme.com","first_name": "Alex","last_name": "Morgan","job_title": "Operations Manager","mobile": "+44 7700 900000","custom_fields": {"extension": "412"}}'

POST/api/v1/users/import

Import people

Upserts up to 5,000 people in one call, matched on email address. Departments named in a row are created if they do not exist.

users:writeplan feature: csv_import

Parameters

JSON body

usersRequired
listThe rows. Each accepts the same fields as Create a person, plus a department name string.
example: [{"email":"sam@acme.com","first_name":"Sam","last_name":"Okafor","department":"Finance"}]

Example request body

json

{
  "users": [
    {
      "email": "sam.okafor@acme.com",
      "first_name": "Sam",
      "last_name": "Okafor",
      "job_title": "Management Accountant",
      "department": "Finance"
    }
  ]
}

Example response

json

{
  "imported": 1,
  "created": 1,
  "updated": 0,
  "skipped": [],
  "departments_created": 1
}

Copy and paste

curl -X POST "https://api.usesigned.co.uk/api/v1/users/import" \
  -H "X-API-Key: $SIGNED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"users": [{"email": "sam.okafor@acme.com","first_name": "Sam","last_name": "Okafor","job_title": "Management Accountant","department": "Finance"}]}'

Worth knowing

Rows are matched on email, so re-running an import updates rather than duplicates. Pass a department name rather than an ID to have it created on demand.

GET/api/v1/users/{id}

Get a person

Returns one person, including custom fields.

users:read

Parameters

In the path

idRequired
stringUser ID.
uuid

Example response

json

{
  "user": {
    "id": "7c3f2b1a-0d4e-4f5a-8b9c-1d2e3f4a5b6c",
    "email": "alex.morgan@acme.com",
    "display_name": "Alex Morgan",
    "active": true,
    "custom_fields": {
      "extension": "412"
    }
  }
}

Copy and paste

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

PATCH/api/v1/users/{id}

Update a person

Updates a person. Send only the fields you want to change. Set active to false to stop issuing them a signature without deleting their record.

users:write

Parameters

In the path

idRequired
stringUser ID.
uuid

JSON body

emailOptional
stringEmail address.
up to 255 characters · email
display_nameOptional
stringName shown in signatures.
up to 255 characters
first_nameOptional
stringFirst name.
up to 255 characters
last_nameOptional
stringLast name.
up to 255 characters
job_titleOptional
stringJob title.
up to 255 characters
department_idOptional
stringDepartment, or null to remove them from one.
uuid
phoneOptional
stringLandline or office number.
up to 100 characters
mobileOptional
stringMobile number.
up to 100 characters
companyOptional
stringOverrides the company default.
up to 255 characters
websiteOptional
stringOverrides the website default.
up to 255 characters
addressOptional
stringOverrides the address default.
up to 2000 characters
linkedinOptional
stringLinkedIn URL or handle.
up to 255 characters
twitterOptional
stringX, formerly Twitter, URL or handle.
up to 255 characters
photo_urlOptional
stringPublic URL of their photo.
up to 2000 characters
custom_fieldsOptional
objectExtra values, available to templates by key.
activeOptional
booleanWhether they get a signature.

Example request body

json

{
  "job_title": "Head of Operations",
  "custom_fields": {
    "extension": "412",
    "team": "Ops"
  }
}

Example response

json

{
  "user": {
    "id": "7c3f2b1a-0d4e-4f5a-8b9c-1d2e3f4a5b6c",
    "job_title": "Head of Operations"
  }
}

Copy and paste

curl -X PATCH "https://api.usesigned.co.uk/api/v1/users/{id}" \
  -H "X-API-Key: $SIGNED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_title": "Head of Operations","custom_fields": {"extension": "412","team": "Ops"}}'

DELETE/api/v1/users/{id}

Delete a person

Removes a person and any rule that targeted them individually. Prefer setting active to false if you may need the record again.

users:write

Parameters

In the path

idRequired
stringUser ID.
uuid

Example response

json

{
  "deleted": true
}

Copy and paste

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

GET/api/v1/users/{id}/signature

Get a person’s signature

Resolves which template applies to this person and returns the rendered HTML. Banners and the disclaimer are included.

signature:read

Parameters

In the path

idRequired
stringUser ID.
uuid

Example response

json

{
  "html": "<table><tr><td><strong>Alex Morgan</strong><br>Head of Operations</td></tr></table>",
  "text": "Alex Morgan\nHead of Operations",
  "template_id": "b8e0f1a2-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
  "template_version": 5
}

Copy and paste

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

Worth knowing

Returns 404 if no template applies, which usually means the person is inactive and there is no default template.