Developer API: fetch an employee's signature programmatically

How do you turn on the API?

The API is off by default. An administrator of your organization turns it on in the console, under Settings → “Developer API”. While it is off, every authenticated request receives a 403 API_DISABLED error.

The same card lets administrators create and revoke API keys.

The API is meant for server-to-server calls: it cannot be called from a browser, and a request carrying an Origin header from another site is refused (403). It does not change signatures, contact details or assignments; only the user's seat and the send counter are updated (see Seats and billing).

Authentication by API key

Every request carries an Authorization: Bearer atom_live_… header with an API key. It is the only authentication mode: any other credential is refused.

• Create it in Settings → “Developer API” → New key, and give it a name (for example “CRM integration”).
• It is shown only once, when you create it. Copy it into a secrets vault: ATOM keeps only a fingerprint and cannot retrieve it.
• An organization can have at most 10 active keys. Each key shows its creation date and last use; revocation is immediate.
• A key gives access to the signatures of every user in your organization: never put it in a web page or a code repository.
• It is independent of the Outlook add-in: renewing one does not affect the other.

Signature routes

Base URL: https://signatures.atomsolutions.ca. All responses are JSON and carry Cache-Control: no-store.

GET /api/v1/whoami

Checks the credentials and returns your organization and the name of the key used.

Response: { "tenant": { "id": "11111111-2222-3333-4444-555555555555", "name": "Example Firm Inc." }, "auth": "key", "keyName": "CRM integration", "apiEnabled": true }. tenant.id is your Microsoft 365 organization's identifier; auth is always key.

GET /api/v1/signatures — a user's signatures

Lists the signatures assigned to a user, so you can let someone choose which one to use. The user parameter follows the same rules as the preview (required, an address from a domain of your organization). Signatures are in priority order; only the ID and the name are returned, never the HTML.

Response: { "signatures": [ { "id": 12, "name": "…", "isDefault": true } ], "defaultSignatureId": 12 }. isDefault marks the signature that GET /api/v1/signature would return without signatureId or recipients; if none fits, defaultSignatureId is null. This call counts neither a seat nor a send.

A signature's ID is also in the console: the signatures list shows an “ID” column when the API is turned on, and clicking the ID copies it.

GET /api/v1/signature — preview

Returns a user's HTML signature, as Outlook would receive it. Parameters:

• user: the user's address. Required, and it must belong to a domain of your organization. An address from another domain gives 404 USER_NOT_FOUND.
• compose: new (default), reply or forward. A signature can have a shorter or different version for replies and forwards.
• recipients: the recipients' domains, separated by commas (50 at most), for signatures whose content depends on the recipient.
• signatureId: optional, the ID of a specific signature, taken from GET /api/v1/signatures. Without it, the user's usual signature is returned. It must be assigned to the user, otherwise 404 SIGNATURE_NOT_FOUND; a value that is not a positive integer gives 400 INVALID_REQUEST.

The preview returns a signature you can use as is: it takes the user's seat (see Seats and billing), but counts no send.

Response: { "matched": true, "html": "…", "signatureId": 12, "name": "…", "mode": "full" }. The mode field tells which version was rendered (full, compact, custom or none); with none, html is empty and there is nothing to add to the message.

POST /api/v1/signature/send — signature for a send

Same response as the preview, with a JSON body { "user", "compose", "recipients", "signatureId" }. signatureId is optional: an integer or a string of digits, with the same rules as the preview. A refused signatureId (404) takes no seat. The difference is accounting: on top of the user's seat, this call counts the send, exactly like an email sent from Outlook (see Seats and billing). Call it once per email actually sent.

Satisfaction survey results

If your organization adds a satisfaction survey to its signatures, the API returns its aggregated results, for example to show them in an internal dashboard.

They return totals only: never a comment, a respondent's address or a result per employee or per signature. A result based on fewer than 10 responses is not broken down: it only contains "insufficient": true, with no count or value.

GET /api/v1/feedback/surveys

The organization's surveys: { "surveys": [ { "id": 12, "name": "…", "scale": "csat3", "status": "active", "created_at": "…" } ] }. The scale is csat3 (three faces, scores 1 to 3), nps (0 to 10) or stars5 (1 to 5 stars); the status is active, paused or archived.

GET /api/v1/feedback/summary — result for a period

Parameters:

• survey: the survey's numeric identifier. Required. A survey that does not exist or belongs to another organization gives 404 SURVEY_NOT_FOUND.
• from (inclusive) and to (exclusive): optional, in ISO 8601 format: a date (2026-10-01, read as UTC) or a date-time with a time zone (2026-10-01T00:00:00Z or 2026-10-01T00:00:00-04:00). A date-time without a time zone is refused (400), as is a period where from does not come before to.

Response: { "survey": 12, "scale": "csat3", "insufficient": false, "count": 48, "value": 0.7916666666666666, "distribution": { "1": 3, "2": 7, "3": 38 } }. The meaning of value depends on the scale: for csat3, the share of “satisfied” scores (a fraction from 0 to 1, not rounded); for nps, the NPS score (-100 to 100, with promoters, passives and detractors); for stars5, the average star rating.

GET /api/v1/feedback/timeseries — trend over time

Same parameters, plus interval: day (default) or week. The response contains a series array, with one result per day or week that received responses (bucket = first day of the interval, Monday for a week, Eastern time). Each interval follows the same 10-response rule.

# List the surveys
curl -s -H "Authorization: Bearer $ATOM_API_KEY" \
  https://signatures.atomsolutions.ca/api/v1/feedback/surveys

# Result of survey 12 since October 1, then week by week
curl -s -H "Authorization: Bearer $ATOM_API_KEY" \
  "https://signatures.atomsolutions.ca/api/v1/feedback/summary?survey=12&from=2026-10-01"
curl -s -H "Authorization: Bearer $ATOM_API_KEY" \
  "https://signatures.atomsolutions.ca/api/v1/feedback/timeseries?survey=12&interval=week"

These routes use no seat and count no send.

Examples

With an API key in an environment variable:

# Check the key
curl -s -H "Authorization: Bearer $ATOM_API_KEY" \
  https://signatures.atomsolutions.ca/api/v1/whoami

# Preview a user's signature
curl -s -H "Authorization: Bearer $ATOM_API_KEY" \
  "https://signatures.atomsolutions.ca/api/v1/signature?user=marie.tremblay@example.ca"

# Signature for a real send
curl -s -X POST -H "Authorization: Bearer $ATOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user":"marie.tremblay@example.ca","compose":"new"}' \
  https://signatures.atomsolutions.ca/api/v1/signature/send

To pick a specific signature, list the user's signatures first, then pass the chosen ID as signatureId:

# The signatures offered to the user
curl -s -H "Authorization: Bearer $ATOM_API_KEY" \
  "https://signatures.atomsolutions.ca/api/v1/signatures?user=marie.tremblay@example.ca"

# Preview signature 12, then signature 12 for a real send
curl -s -H "Authorization: Bearer $ATOM_API_KEY" \
  "https://signatures.atomsolutions.ca/api/v1/signature?user=marie.tremblay@example.ca&signatureId=12"
curl -s -X POST -H "Authorization: Bearer $ATOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user":"marie.tremblay@example.ca","signatureId":12}' \
  https://signatures.atomsolutions.ca/api/v1/signature/send

The typical case: adding the signature to an email sent through Microsoft Graph. In Node.js (version 18 or later):

const res = await fetch('https://signatures.atomsolutions.ca/api/v1/signature/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ATOM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ user: 'marie.tremblay@example.ca', compose: 'new' }),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const { html: signature } = await res.json();

// Graph email body (POST /users/{upn}/sendMail)
const body = { contentType: 'HTML', content: `<p>Hello,</p>${signature}` };

The OpenAPI specification describes every route and can be imported into a tool such as Postman or into a client generator.

Error codes

Every error has the same shape: { "error": { "code": "…", "message": "…" } }, with one exception: a request refused for an Origin header from another site (see the table).

What are the rate limits?

Over a one-minute window:

• 120 requests per API key;
• 600 requests per organization, all keys combined;
• 300 requests per IP address, before authentication.

Beyond that, the API answers 429 RATE_LIMITED with a Retry-After header. A signature rarely changes: cache the preview on your side and keep signature/send for emails actually sent.

Seats and billing

The model is the Outlook add-in's: a distinct user who sends signed email occupies one seat.

• The list (GET /api/v1/signatures) counts nothing: it only returns IDs and names, never the HTML.
• The preview (GET /api/v1/signature) takes the user's seat, without counting a send.
• The send (POST /api/v1/signature/send) takes the user's seat and counts the send, like an email sent from Outlook.
• A user already counted does not take a second seat. If the subscription's seat limit is reached for a user not yet counted, both the preview and the send answer 409 SEAT_LIMIT.
• If the organization's subscription is not active, the response is 402 BILLING_INACTIVE.

For pricing and seat management, see pricing.

Frequently asked questions