A PHP implementation of Yousign API client. – Yousign API client Documentation

Yousign API client is a wrapper for the Yousign API v2 in PHP.

Its purpose is to use this API without having to write the HTTP calls yourself and to exploit the data returned through an object model.

If you still want to make HTTP calls to check the API responses, this is possible thanks to the low-level calls.

It provides several layers:

A low-level API client (Yousign\YousignClient)
An API wrapper (Yousign\YousignApi)
- A wrapper for the basic procedure
- A wrapper for the extended procedure

As all the API calls are wrapped into an object model, it aims to be a full-featured client.

All subsequent types (Member, Procedure, File, etc…) are implemented too.

Requirements
Install
Quick start
Basic mode
Advanced mode

Requirements

PHP 7.4+
You have to create your account on Yousign platform to get an API token before using this library.

Install

composer require landrok/yousign-api

Quick start

Making your first call

In this example, we will get all users in staging mode.

use Yousign\YousignApi;

/*
 * token
 */
$token = '123456789';

$yousign = new YousignApi($token);

$users = $yousign->getUsers();

$users contains an iterable UserCollection object. This collection

All API responses are converted into objects that are iterable when it’s a collection (ie a list of users) or an item (an user itself).

These objects have several methods:

toArray()

You can use toArray() method to dump all data as a PHP array.

print_r(
    $users->toArray()
);

toJson()

You can use toJson() method to serialize all data as a JSON object.

echo $users->toJson();

Iterate over a collection

You can iterate over all items of a collection.

foreach ($users as $user) {
    /*
     * For each User model, some methods are available
     */

    // toArray(): to get all property values
    print_r($user->toArray());

    // get + property name
    echo PHP_EOL . "User.id=" . $user->getId();

    // property (read-only)
    echo PHP_EOL . "User.id=" . $user->id;

    // Some properties are models that you can use the same way
    echo PHP_EOL . "User.Group.id=" . $user->getGroup()->getId();
    echo PHP_EOL . "User.Group.id=" . $user->group->id;

    // Some properties are collections that you can iterate
    foreach ($user->group->permissions as $index => $permission) {
        echo PHP_EOL . "User.Group.Permission.name=" . $permission->getName();
    }

    // At any level, you can call a toArray() to dump the current model
    // and its children
    echo PHP_EOL . "User.Group=\n";
    print_r($user->group->toArray());
    echo PHP_EOL . "User.Group.Permissions=\n";
    print_r($user->group->permissions->toArray());
}

Basic Mode

Let’s create your first signature procedure in basic mode.

In this example, we will accomplish this mode with low-level features.

use Yousign\YousignApi;

/*
 * Production mode
 */
$production = false;

/*
 * Instanciate API wrapper
 */
$yousign = new YousignApi($token, $production);

/*
 * 1st step : send a file
 */
$file = $yousign->postFile([
    'name'    => 'My filename.pdf',
    'content' => base64_encode(
        file_get_contents(
            '/my_storage_path/test-file-1.pdf'
        )
    )
]);

/*
 * 2nd step : create the procedure
 */
$procedure = $yousign->postProcedure([
    "name"        => "My first procedure",
    "description" => "Awesome! Here is the description of my first procedure",
    "members"     => [
        [
            "firstname" => "John",
            "lastname" => "Doe",
            "email" => "john.doe@yousign.fr",
            "phone" => "+33612345678",
            "fileObjects" => [
                [
                    "file" => $file->getId(),
                    "page" => 2,
                    "position" => "230,499,464,589",
                    "mention" => "Read and approved",
                    "mention2" => "Signed by John Doe"
                ]
            ]
        ]
    ]
]);

// toJson() supports all PHP json_encode flags
echo $procedure->toJson(JSON_PRETTY_PRINT);

When the procedure is created, you can retrieve all the data with the getters or dump all data with toJson() and toArray() methods.

It would output something like:

{
    "id": "/procedures/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "name": "My first procedure",
    "description": "Awesome! Here is the description of my first procedure",
    "createdAt": "2018-12-01T11:49:11+01:00",
    "updatedAt": "2018-12-01T11:49:11+01:00",
    "finishedAt": null,
    "expiresAt": null,
    "status": "active",
    "creator": null,
    "creatorFirstName": null,
    "creatorLastName": null,
    "workspace": "/workspaces/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "template": false,
    "ordered": false,
    "parent": null,
    "metadata": [],
    "config": [],
    "members": [
        {
            "id": "/members/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "user": null,
            "type": "signer",
            "firstname": "John",
            "lastname": "Doe",
            "email": "john.doe@yousign.fr",
            "phone": "+33612345678",
            "position": 1,
            "createdAt": "2018-12-01T11:49:11+01:00",
            "updatedAt": "2018-12-01T11:49:11+01:00",
            "finishedAt": null,
            "status": "pending",
            "fileObjects": [
                {
                    "id": "/file_objects/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                    "file": {
                        "id": "/files/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                        "name": "The best name for my file.pdf",
                        "type": "signable",
                        "contentType": "application/pdf",
                        "description": null,
                        "createdAt": "2018-12-01T11:36:20+01:00",
                        "updatedAt": "2018-12-01T11:49:11+01:00",
                        "sha256": "bb57ae2b2ca6ad0133a699350d1a6f6c8cdfde3cf872cf526585d306e4675cc2",
                        "metadata": [],
                        "workspace": "/workspaces/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                        "creator": null,
                        "protected": false,
                        "position": 0,
                        "parent": null
                    },
                    "page": 2,
                    "position": "230,499,464,589",
                    "fieldName": null,
                    "mention": "Read and approved",
                    "mention2": "Signed by John Doe",
                    "createdAt": "2018-12-01T11:49:11+01:00",
                    "updatedAt": "2018-12-01T11:49:11+01:00",
                    "parent": null,
                    "reason": "Signed by Yousign"
                }
            ],
            "comment": null,
            "notificationsEmail": [],
            "operationLevel": "custom",
            "operationCustomModes": [
                "sms"
            ],
            "operationModeSmsConfig": null,
            "parent": null
        }
    ],
    "subscribers": [],
    "files": [
        {
            "id": "/files/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "name": "The best name for my file.pdf",
            "type": "signable",
            "contentType": "application/pdf",
            "description": null,
            "createdAt": "2018-12-01T11:36:20+01:00",
            "updatedAt": "2018-12-01T11:49:11+01:00",
            "sha256": "bb57ae2b2ca6ad0133a699350d1a6f6c8cdfde3cf872cf526585d306e4675cc2",
            "metadata": [],
            "workspace": "/workspaces/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "creator": null,
            "protected": false,
            "position": 0,
            "parent": null
        }
    ],
    "relatedFilesEnable": false,
    "archive": false,
    "archiveMetadata": [],
    "fields": [],
    "permissions": []
}

If you want to create your signature procedure in basic mode with a more high-level feature, see this manual.

Advanced Mode

Here is how to create a procedure in 5 steps with the advanced mode.

use Yousign\YousignApi;

/*
 * Token
 */
$token = '123456789';

/*
 * Production mode
 */
$production = false;

/*
 * Instanciate API wrapper
 */
$yousign = new YousignApi($token, $production);

/*
 * Step 1 - Create your procedure
 */
$procedure = $yousign->postProcedure([
    "name"        => "My first procedure",
    "description" => "Description of my procedure with advanced mode",
    "start"       => false,
]);

/*
 * Step 2 - Add the files
 */
$file = $yousign->postFile([
    'name'    => 'Name of my signable file.pdf',
    'content' => base64_encode(
        file_get_contents(
            dirname(__DIR__, 2) . '/tests/samples/test-file-1.pdf'
        )
    ),
    'procedure' => $procedure->getId(),
]);

/*
 * Step 3 - Add the members
 */
$member = $yousign->postMember([
    "firstname"     => "John",
    "lastname"      => "Doe",
    "email"         => "john.doe@yousign.fr",
    "phone"         => "+33612345678",
    "procedure"     => $procedure->getId(),
]);


/*
 * Step 4 - Add the signature images
 */
$fileObject = $yousign->postFileObject([
    "file"      => $file->getId(),
    "member"    => $member->getId(),
    "position"  => "230,499,464,589",
    "page"      => 2,
    "mention"   => "Read and approved",
    "mention2"  => "Signed By John Doe"
]);

 /*
  * Step 5 - Start the procedure
  */
$procedure = $yousign->putProcedure(
    $procedure->getId(), [
        "start" => true,
    ]
);


echo $procedure->toJson(JSON_PRETTY_PRINT);

In step 3, you may add several members. In step 4, you may add one or more signature images for each one.

Contribute on Github
To discuss new features, make feedback or simply to share ideas, you can contact me on Mastodon at https://cybre.space/@landrok
Create an account and an API token on Yousign Sandbox sign-up
Official API manual

Edit this document on GitHub

Table of contents