# QuickStart Guide ### An example workflow for signing documents 1. Register via OAuth for the target user - retrieve their Tenant Id via [/api/Tenant/List](https://fuseworks.gitbook.io/fusesign/api-references/tenant#api-tenant-list) 2. Upload document(s) via the[ **/api/Document/Upload**](https://fuseworks.gitbook.io/fusesign/api-references/document#api-document-upload) endpoint. * Record the ID(s) of the uploaded documents. 3. Create a new bundle via the [**/api/Bundle/Create**](https://fuseworks.gitbook.io/fusesign/api-references/bundle#api-bundle-create) endpoint. * Register your callback **WebhookUrl** for that specific bundle. * Note: Certain authentication methods require customer details. *E.g. SMStoSign requires the mobile number to be uploaded on customer creation.* 4. The signing customer opens and signs the documents via the FuseSign platform. * Receive and react to webhook events.\ \[*Customer opened, customer signed, bundle finalised etc*] 5. Once all documents are signed and the bundle is finalised - retrieve the bundle via [**/api/Bundle/Get**](https://fuseworks.gitbook.io/fusesign/api-references/bundle#api-bundle-get) - This will confirm the status and include the Document Ids to be used in [**/api/Document/Download**](https://fuseworks.gitbook.io/fusesign/api-references/document#api-document-download) and also included in the **SignedPDFDownloadUrl** attribute per document. 6. Once documents are downloaded - Archive the bundle via [**/api/Bundle/Archive**](https://fuseworks.gitbook.io/fusesign/api-references/bundle#api-bundle-archive) *(This will be done in 60 days automatically once the signed document download has been registered, don't worry we'll keep reminding you via webhooks :) )* #### Authentication To get started you will need a developer account. Please contact to arrange a test account. There are two main methods of authentication: 1. **Tenant token** - Uses Bearer OAuth2 to login on behalf of an existing FuseSign user. \ \&#xNAN;*\[MOST COMMON]*. * This will include a **ClientId** and **ClientSecret** *(see workflow below)* > Please note that HTTP request header is required when making a OAuth Post call, which needs to be sent as application/json type. 2. **Wholesale token** - A simple API key which is provided to you to act as a key for your FuseSign account * This will include a **X-API-Token** which can be used in the header and attached to a developer user. All operations require a **wholesale token** (or OAuth2 **bearer access token**) and a **TenantId**. #### OAuth 2 Register Method **Step 1 - End user redirection**
Redirect URLhttps://api.fuse.work/api/Session/OAuthRegister
**HTTP GET** * `response_type` with the value `code` * `client_id` with the client identifier * `redirect_uri` with the client redirect URI. This parameter must match the registered redirect domain below. * `scope` a space delimited list of scopes. Current scopes include: `FUSESIGN` * `state` with a [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) token. This parameter is optional but highly recommended. You should store the value of the CSRF token in the user's session to be validated when they return. **Response** * `code` with the authorization code * `state` with the state parameter sent in the original request. You should compare this value with the value stored in the user's session to ensure the authorization code obtained is in response to requests made by this client rather than another client application. **Step 2 - Get Token**
Redirect URLhttps://api.fuse.work/api/Session/OAuthGetToken
**HTTP POST** * `grant_type` with the value of `authorization_code` * `client_id` with the client identifier * `client_secret` with the client secret * `redirect_uri` with the same redirect URI the user was redirect back to * `code` with the authorization code from the query string **Response** * `token_type` this will be the word `Bearer` (to indicate a bearer token) * `expires_in` a date time offset representing the TTL of the access token (i.e. when the token will expire) * `access_token` the access token itself * `refresh_token` a refresh token that can be used to acquire a new access token when the original expires * `refresh_token_expires_in` a date time offset representing the TTL of the refresh token (i.e. when the token will expire) * `default_tenant_id` for the user oauth method, this represents the tenantId selected by the user at connection time. **Please note the request is a JSON body, not form data.** **Step 3 - Refresh Token** | RefreshToken URL | | | ---------------- | ----------------------------------------------------- | **HTTP POST** * `grant_type` with the text value `refresh_token` * `refresh_token` with the refresh token * `client_id` with the the client's ID * `client_secret` with the client's secret **Response** * `token_type` this will be the word `Bearer` (to indicate a bearer token) * `expires_in` a date time offset representing the TTL of the access token (i.e. when the token will expire) * `access_token` the access token itself * `refresh_token` a refresh token that can be used to acquire a new access token when the original expires * `refresh_token_expires_in` a date time offset representing the TTL of the refresh token (i.e. when the token will expire) * `default_tenant_id` for the user oauth method, this represents the tenantId selected by the user at connection time. **Step 4 - Revoke Token (at end of life)** | RefreshToken URL | | | ---------------- | ---------------------------------------------------- | **HTTP POST** * `refresh_token` with the refresh token * `client_id` with the the client's ID **Response** Http 200 if successful *** #### Wholesale token Method This method is much simpler - all calls are made with **X-API-Token** in the header. This Token is tied to a specific user with account privileges. I.e. over a single tenant.\ \ For more information or to discuss your use case please contact ### Example: Bundle Create The basic use case for a Bundle is to use the [Bundle/Create](https://fuseworks.gitbook.io/fusesign/api-references/bundle#api-bundle-create) endpoint A simple example payload is: ```json { "Subject": "This is the subject field in the email", "Body": "Hello Signer, Could you please sign please", "CreateMode": "CreateAndSend", "Customers": [ { "Customer": { "Name": "MY NAME HERE", "Email": "MY EMAIL HERE", "PhoneNumber": "+61411111111" } } ], "Documents": [ { "DisplayName": "Name of Document", "DocumentUrl": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "DocumentOrder": 0, "CustomerSigners": [ 0 ] } ], "ViewMode": "SmsToSign", "Settings": { "WebhookUrl": "https://example.com/my_fusesign_webhookID" } } ``` There are many more options available to this object, see below for the full specifications. Configuration available: * Set a **Metadata** for any document, client or bundle for retrieval and search. * Upload a document via Base64 content or via File upload (via [**/api/document/upload**](https://fuseworks.gitbook.io/fusesign/api-references/document#api-document-upload)) * Change the ViewMode: Available **SmsToView**, **SmsToSign**, **EmailToSign**, **EmailToView** * Set a **DueDate**, **DueReminderMode** and **OverdueReminderMode** reminder modes. * Set a "**CreatedBy**" email address \[if impersonation is enabled] to allow users to create bundles as other user(s) * Set a customer with **NoMobile** attribute (which allows EmailToSign, EmailToView auth method to be used) * Utilise the "**LastSigner": true** attribute (all other signers must sign first before this person is notified. * *and many more...*