Post an agreement to be signed

POST

/v1/tenant/{tenantKey}/agreement

const url = 'https://sender.api.kivra.com/v1/tenant/example/agreement';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"subject":"Employment agreement","type":"agreement","vat_number":"SE556840226601","expiration_days":60,"original":{"name":"agreement1025.pdf","content_type":"application/pdf","data":"REVBREJFRUY="},"parties":[{"ssn":"197701032380","name":"Jan-Erik Karlsson","email":"je.karlsson@email.nu","role":"signer"},{"ssn":"198112172385","name":"Gustav Larsson","email":"gustav123@mymail.com","role":"delegate"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://sender.api.kivra.com/v1/tenant/example/agreement \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "subject": "Employment agreement", "type": "agreement", "vat_number": "SE556840226601", "expiration_days": 60, "original": { "name": "agreement1025.pdf", "content_type": "application/pdf", "data": "REVBREJFRUY=" }, "parties": [ { "ssn": "197701032380", "name": "Jan-Erik Karlsson", "email": "je.karlsson@email.nu", "role": "signer" }, { "ssn": "198112172385", "name": "Gustav Larsson", "email": "gustav123@mymail.com", "role": "delegate" } ] }'

This resource is used to post an agreement to be signed by the recipients listed in the metadata. An Agreement ID will be returned. Note that the size of the agreement file cannot exceed 1MB.

Authorizations

oAuth2Client
post:kivra.v1.tenant.{tenantKey}.agreement

Parameters

Path Parameters

tenantKey

required

string format: hexadecimal

The unique Key for a Tenant

Request Body

application/json

Agreement

object

subject

required

Name of the agreement

string

Example

Employment agreement

type

required

The type of content, for agreements always use ‘agreement’

string

Example

agreement

vat_number

A valid VAT-identifier, Swedish format: SE[xxxxxxxxxx]01

string

Example

SE556840226601

expiration_days

Number of days an agreement will be available for signing, before expiring. The expiration_days must be between 7 and 180 days

integer

>= 7 <= 180

Example

original

required

object

name

Name of the document file

string

Example

agreement1025.pdf

content_type

The IANA media type corresponding to the file, e.g. “application/pdf”

string

Example

application/pdf

data

Base64-encoded data for the agreement PDF

string format: Base64-encoded data

Example

REVBREJFRUY=

parties

required

List of signers and delegates that are requested to sign the agreement

Array<object>

AgreementParties

object

ssn

User’s unique SSN, format: YYYYMMDDnnnn

string

Example

197701032380

name

Name of the user

string

Example

Jan-Erik Karlsson

email

Email to be used to contact the user

string

Example

je.karlsson.hem@email.nu

role

The role of the user in this signature flow

string

Allowed values: signer delegate

Example

signer

Example

[
  {
    "ssn": "197701032380",
    "name": "Jan-Erik Karlsson",
    "email": "je.karlsson@email.nu",
    "role": "signer"
  },
  {
    "ssn": "198112172385",
    "name": "Gustav Larsson",
    "email": "gustav123@mymail.com",
    "role": "delegate"
  }
]

Responses

200

Agreement created succesfully

application/json

string

Example

15544700816b7d63c83d6e476493879b5043ec9d7b

400

Agreement PDF was invalid

application/json

Error40045

object

code

The 5-digits error code

string

short_message

A short message explaining the error

string

long_message

A text message explaining the error

string

Example

{
  "code": 40045,
  "short_message": "PDF was invalid",
  "long_message": "The supplied agreement PDF was invalid. Please check that the file is a valid PDF"
}