Reference, v1

People

Calls are made to https://api.footer365.net with an API key as a bearer token. This page is generated from the API's own description, which you can download.

GET /v1/users

Lists people and groups a page at a time

The people and mail-enabled groups in your organisation's directory, ordered by address, a page at a time. Pass nextCursor back as cursor for the next page. Needs directory.read.

Parameter	In	Type	About it
`limit` (optional)	query	integer	How many to return, up to 200.
`cursor` (optional)	query	string	Where the previous page ended, as nextCursor gave it.

Answers 200 with UserPage.

GET /v1/users/{user}

Reads one person and their details

One person or group, by primary address or id, with every field a signature can use: the value Microsoft 365 holds, the value held in Footer365 and where it came from, and the value signatures use. Needs directory.read.

Parameter	In	Type	About it
`user`	path	string	The person's primary address or id.

Answers 200 with UserDetail.

PATCH /v1/users/{user}

Sets or clears details held for one person

Sets details by the same rules as the User details import: a field Microsoft 365 holds is replaced only where the organisation has set it to be, a value the person set through staff self-service is left alone, and a custom field's value must fit its type. Null or an empty string clears a value held in Footer365. Nothing is changed unless every field can be. Needs directory.write.

Parameter	In	Type	About it
`user`	path	string	The person's primary address or id.

Takes UserChange. Answers 200 with UserDetail.

GET /v1/users/{user}/signature

Reads the signature a person's rules give one kind of message

The signature the person's rules give a message, as HTML and as plain text, built from their details as signatures use them now. Campaign banners and disclaimers are left out, because they belong to a message rather than the person. When the rule chooses between several templates at random, one is drawn for each request, unless the person's own default signature is one of them. Needs templates.read.

Parameter	In	Type	About it
`user`	path	string	The person's primary address or id.
`type` (optional)	query	string	new, reply or forward; new when left out.
`recipients` (optional)	query	string	external or internal; external when left out.

Answers 200 with UserSignature.

Types

`UserPage`

Property	Type	About it
`items`	array of UserSummary	The people on this page.
`nextCursor`	string, or null	Pass as cursor for the next page; null on the last page.

`UserDetail`

Property	Type	About it
`id`	string (uuid)	The Footer365 id.
`email`	string	The primary address.
`displayName`	string	The display name.
`type`	string	mailbox or group.
`enabled`	boolean	Whether the account is enabled in Microsoft 365.
`fields`	array of UserField	Each field.

`UserChange`

Property	Type	About it
`fields`	map of string, or null	Each field, by merge tag or by the organisation's name for it, with its new value; null or empty clears it.

`UserSignature`

Property	Type	About it
`email`	string	The person's primary address.
`templateId`	string (uuid)	The template it is built from.
`template`	string	The template's name.
`appliesTo`	string	The kind of message asked for, such as "External - New".
`html`	string	The signature as HTML.
`text`	string	The signature as plain text.

`UserSummary`

Property	Type	About it
`id`	string (uuid)	The Footer365 id.
`email`	string	The primary address.
`displayName`	string	The display name.
`type`	string	mailbox or group.
`enabled`	boolean	Whether the account is enabled in Microsoft 365.
`jobTitle`	string, or null	The job title in Microsoft 365.
`department`	string, or null	The department in Microsoft 365.

`UserField`

Property	Type	About it
`field`	string	The merge tag, which is also the name to set it by.
`name`	string, or null	The organisation's name for one of its own fields, or null for a standard field.
`value`	string, or null	The value signatures use, or null when the field is left out.
`directoryValue`	string, or null	The value Microsoft 365 holds, or null.
`footer365Value`	string, or null	The value held in Footer365, or null.
`replacesDirectory`	boolean	Whether the value held in Footer365 is used instead of the directory's.
`source`	UserFieldSource, or null

`UserFieldSource`

Property	Type	About it
`kind`	string	portal, import, staff or source. A value set through the API is recorded as an import, and one a directory source set is recorded as source.
`by`	string, or null	Who set it, by name, or for a directory source the name it had when the value was set.
`at`	string (date-time), or null	When, in UTC, or null when not known.

Errors are written the same way for every call; see Errors. Answers may gain fields within a version, so ignore any you do not recognise.