Skip to main content
This guide sends salary adjustment letters in bulk. Each letter is signed for the employer by an HR director under a standing authorisation, and goes out to the employee to accept. The employee is the only person emailed. Do it end to end with a vsk_test_ key first. Nothing a test key makes binds anybody, and the mandate and the letters are watermarked.

​
Before you start

  • Standing authorisations are switched on for your organisation by Vumasign, separately for sandbox and live. Until then every request answers standing_authorisations_not_enabled.
  • A key that names both scopes: authorisations:invite to request the authorisation and authorisations:apply to apply it. A full-access key holds neither. An owner or admin adds them under Settings → API keys.
  • A brand for the letters. The authorisation covers only documents sent under that brand.

​
1. Mark the letter

Use the ordinary text tags. Nothing in the letter says “pre-signed”: the choice is made when you send.
Make it a template with the roles Employee and Employer. On the pre-signed role, Vumasign fills the signature, the grantor’s name, the title they signed the mandate with, the legal entity and the date. The figure is yours: send it as a locked value for the key new_salary. Don’t put an email tag on the pre-signed role; it is refused.

​
2. Request the authorisation, under a test key

Ask the HR director to sign the mandate. Under a test key the grantor must be a verified test recipient or a member of your organisation, so use your own address for the trial:
valid_until may be at most 12 months away. Keep the id the answer returns. The grantor receives the mandate, enters the code emailed to them, and signs it. When the signed mandate is sealed you receive authorisation.granted, and the authorisation reads active.

​
3. Send a batch, under the same test key

Each row names the employee as a signer and the authorisation on the employer’s role, with the figure locked:
Post it to POST /api/v1/envelopes/batches. Each letter goes out already signed by the employer. In each envelope the employer’s recipient has completion_basis: "standing_authorisation", and the grantor receives no email about any letter. The employee must be a signing recipient. A letter with nobody else to sign or approve is refused authorisation_without_signer.

​
4. Go live

Repeat steps 2 and 3 with a vsk_live_ key and the real grantor. A sandbox authorisation never pre-signs a live letter, and a live one never pre-signs a sandbox letter.

​
How a batch behaves

  • Refused up front, or not at all. If the authorisation ends within 1 hour of the request, the whole batch is refused authorisation_expires_during_batch before any letter is created or sent. Use an authorisation with more time left.
  • A revoke part-way through stops the rows after it that name the same authorisation. They are not sent, each says why, and each stays a draft. Letters already sent stay signed: the authorisation was in force when each was applied.
  • Each row is its own answer. A row refused for its own data does not stop the others.

​
In the dashboard

An owner or admin can do the same from Send in bulk: choose “Pre-sign as …” for the employer’s role, choose the file, and confirm the sentence that names the grantor, the role, the authorisation and how many letters. The bulk screen sends under your default brand. Standing authorisations · Text tags · Test keys and live keys · Webhooks