💼 Creating a Deed

A step-by-step guide to operate on a simple deed through the API.

🤔 What's a Deed?

Head over to the Entities page to understand what a ✍️Deed entity is and all the different kinds of deeds.

Creating a Deed through the API

To create a ✍️Deed entity, it is sufficient to perform a single HTTP POST 📌API request.

The following is an example of creating a ✍️Deed entity along with a new 📂Folder entity which will contain it.

Node.js

const res = await fetch(`https://staging.gayadeed.it/medusa/deeds?sendInvites=${sendInvites}`, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": accessToken,
    },
    body: JSON.stringify({
        description: "My Test Deed",
        enableChecklist: true, // False if you don't want to enable checklist
        folderCode: "GAYA_CA4316",
        folderName: "My Test Folder",
        folderType: "GENERIC_DOSSIERS",
        kind: "GENERIC",
        signType: "FEQ", // FEA, FEQ or ARCHIVE
        serialNumber: "001", // Can be an arbitrary string
        signatoryUserId: 54316, // User id of the user which will become the signatory of the deed
        participants: [{
            type: "SUBSCRIBER",
            name: "Mario",
            surname: "Rossi",
            email: "mario.rossi@example.it",
            gender: "M",
            fiscalCode: "AAABBBCCCDDDEEEF", // Not mandatory. If present, must follow the italian convention
            address: {
                street: "Via Barletta",
                number: "367",
                city: "Andria",
                cap: "76123",
                district: "BT",
                region: "Puglia",
                country: "IT",
            },
            birthDay: "1999-11-26",
            cityBirthPlace: "Milano",
            districtBirthPlace: "MI",
            birthCountry: "IT",
            citizenship: "IT", // Also called 'nationality'
            identificationDocument: { // Info about the identification document of the participant, optional
                type: "IDENTITY_CARD",
                number: "AAAAAAAAA",
                releaseDate: "2018-12-01",
                expirationDate: "2032-12-01",
                issuer: "MILANO",
                issueCountry: "IT"
            },
            metadata: {
                pec: "mario.rossi@pec.it",
                // any key: value pair can be stored here
            }
        }],
    })
});
const response = await res.json();

A very important parameter is signatoryUserId: this is the id of the user which will become the 👨‍💼Signatory of the deed. All deeds must have a signatory!. Depending on the use case, this can be hardcoded to the user id of the owner of the tenant if you don't care too much about it.

Notice that all country codes follow the ISO 3166-1 Alpha-2 convention.

For each participant, it is possible to specify a great number of personal information regarding them. The only mandatory fields, though, are name, surname and email.

metadata is a key-value store appropriate for storing additional information regarding the participant which might not fit into the original model. In the example, we are using it to store their PEC address.

The response, if successful, will contain our newly generated folder's id and deed's id. Every subsequent operation on this deed will require its id of course!

The response will also contain the invite links, through which the participants can access the deed, identify themselves and sign documents right away. You can read them and send the invitations using your own system, or you can set the sendInvites query parameter to true in order to automatically send invite links to participants through email.

Types enumeration

folderType, kind and participants.type are enumerated strings, which means that only a particular set of values is allowed. Since this enum is frequently updated, please refer to the Swagger for up-to-date list of valid parameters. For example, on the Swagger doc you can search for "gaya.DossierType" to see a list of allowed values for kind, or "gaya.ParticipantType" for participants.type.

For folderType, it is possible to find a list of allowed values here.

Regardless, not passing the allowed values will result in an error.

Appending a Deed to an existing Folder

Given an existing 📂Folder's id, it possible to append a ✍️Deed to that 📂Folder by specifying the parameter folderId in the request payload. If this parameter is not present or it is 0, a new 📂Folder entity will be created alongside the ✍️Deed, following the parameters folderCode, folderName and folderType, which become mandatory. If folderId is specified, these parameters should not be passed as they are ignored.