en English
X

Select Language

Powered by Google TranslateTranslate

We hope you will find the Google translation service helpful, but we don’t promise that Google’s translation will be accurate or complete. You should not rely on Google’s translation. English is the official language of our site.

en English
X

Select Language

Powered by Google TranslateTranslate

We hope you will find the Google translation service helpful, but we don’t promise that Google’s translation will be accurate or complete. You should not rely on Google’s translation. English is the official language of our site.

Remote Document Signing with eSigner CSC API

This guide will show you how to enroll a document signing certificate order with SSL.com’s eSigner service and use the Cloud Signature Consortium (CSC) API to digitally sign a document hash and a PDF file. You can use this guide with either cURL or Postman. We recommend that Postman users install the desktop app for working through the examples.

Sections 1 through 5 of this article demonstrate how to use SSL.com’s production eSigner and eSealing environment. Section 6, titled Testing Remote Document Signing with eSigner CSC API in the Sandbox, shows how to experiment with the CSC API in SSL.com’s Sandbox environment using test certificates.

For this article, you will need:

  • A validated document signing certificate order. Please read this how-to for full instructions on ordering and validation of production certificates. If you would like to order a test certificate in the sandbox environment instead, please proceed to Section 7 of this article.
  • A Client ID (also known as an Application ID. Please refer to this how-to for instructions on generating this credential for either production or sandbox).

SSL.com’s Document Signing Certificates are trusted worldwide to digitally sign and certify Adobe PDF and Microsoft Office documents with secure digital signatures. 

BUY YOUR SSL.COM DOCUMENT SIGNING CERTIFICATE

Check out the pricing guide for eSigner Document Signing

SEE PRICING TIERS

Enroll in eSigner and Set Up Two-Factor Authentication

  1. Before you can start using the CSC API, you’ll need to enroll in eSigner. Navigate to the Orders tab in in your SSL.com account and locate your order.
    Locate order
  2. Click the order’s details link.
    details
  3. Create a and confirm a 4-digit PIN, then click the create PIN button.
    If you need to reset your eSigner PIN, please read this how-to.
    Create PIN
  4. A QR code will appear.
    The next time you reload the page the QR code will not be visible. If you need to to view or reset your eSigner QR code, please read this how-to.
    QR Code
  5. Scan the code into a 2-factor authentication app on your mobile device, such as Google Authenticator or Authy. The app will provide you with one-time passwords (OTPs) for use when signing. Each OTP is valid for 30 seconds.
    OTP in Authy
Tip: You can use eSigner to share organization validated (OV) signing certificates between teammates. Please read Team Sharing for eSigner Document and EV Code Signing Certificates for instructions.

Install Postman and Import API Collections

The instructions in this section are for Postman users only. If you’re using cURL with the CSC API, you can move onto the next section.

  1. Download and unzip the CSC API Postman collection and Document Signing API Postman collection (see https://www.postman.com/sslcom for online SSL.com API collections).
    Postman collections
  2. Download and install the Postman REST Client.
    Postman REST Client download
  3. Launch Postman, then create a new Postman account or sign into an existing one.
    Postman Login
  4. Click the Import button.
    Import button
  5. Click the Upload Files button, navigate to the unzipped API collection files (csc-api-prod.postman_collection.json and document-signing-api-prod.postman_collection.json), and open them.
    Upload Files
  6. Click the Import button.
    Click import button
  7. The API requests you will be working with are now available in the Collections tab on the left side of the Postman window.
    API requests

Retrieve Access Token

The next step is to retrieve an access token from SSL.com. You’ll need your Client ID available, as well as the username and password for your SSL.com account. Access tokens are valid for one hour after they are issued.

Use the clickable tabs below to choose instructions for Postman or cURL:

Postman InstructionscURL Instructions
  1. Select an API request from the CSC API collection.
    select API request
  2. Select the Authorization tab and select OAuth 2.0 from the Type menu.
    Authorization Tab
  3. Enter the following information into the form:
    • Header Prefix: Bearer
    • Token Name: SSLCOM CSC (or any other easy-to-remember name that you prefer)
    • Grant Type: Authorization Code
    • Callback URL: https://upload.esigner.com
    • Authorize using browser: unchecked
    • Auth URL: https://login.ssl.com/oauth2/authorize
    • Access Token URL: https://login.ssl.com/oauth2/token
    • Client ID: [Your Client ID]
    • Client Secret: [Your Client Secret]
    • Scope: service
    • State: [leave blank]
    • Client Authentication: Send as Basic Auth header

    When you are finished, click the Get New Access Token button.
    Get New Access Token

  4. A login form will appear. Enter your SSL.com username and password, then click the Member Login button.
    Account login
  5. Your new access token should appear in Postman. Select the access token text and copy it to the clipboard, then close the Manage Access Tokens dialog box. Paste your access token into a text editor where you can access it easily. Each access token will expire after one hour.
    You can also save your token for re-use in Postman requests, but we have found that it is most reliable to copy and paste the token directly into each request.
    Access Token
  1. Use the following command to request an access token. Replace the values shown in ALL-CAPS with your actual values:
    curl --location --request POST "https://login.ssl.com/oauth2/token" \
    --header "Content-Type: application/json" \
    --data-raw '{
     "client_id"  : "YOUR-CLIENT-ID",
     "client_secret"  : "YOUR-CLIENT-SECRET",
     "grant_type" : "password",
     "username"   : "YOUR-USERNAME",
     "password"   : "YOUR-PASSSWORD"
    }'
  2. You should receive a JSON object containing an access token and a refresh token. Copy the access token value to paste into your API requests. You won’t need the refresh token for these examples.
    Retrieve access token

Sign a Hash

Now that you have an access token, you can begin making API requests and creating signatures. This section will lead you through the five available requests in the Postman CSC collection, resulting in the creation of a digital signature from a document hash.

Get CSC Info (Optional)

Postman InstructionscURL Instructions
  1. You can use the CSC Info request to get information about SSL.com’s cloud signature service. Note that, unlike the others in the collection, this request does not require your access token. To send the request, select CSC Info from the CSC API collection, then click the Send button.
    Send CSC Info Request
  2. Information about the cloud signature service will appear in a JSON object in Postman’s Response field.
    CSC Info
  1. Use the following command to get info about SSL.com’s CSC API service:
    curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ 
    --header "Content-Type: application/json" \ 
    --data-raw "{}"
  2. You will recieve a JSON object with details about the service:
    Get CSC info

CSC Credentials List

The CSC Credentials List request will retrieve a credential you will use in later API requests.

Postman InstructionscURL Instructions
  1. Select CSC Credentials List and click the Authorization tab.
    Authorization tab
  2. Choose Bearer Token from the Type menu, paste your access token into the Token field, then click the Send button.
    Send credentials list request
  3. A JSON object with a list of credential IDs associated with the user will appear in the Response field. Your list will probably contain one value. Copy and paste your credential ID into a text editor for use in later requests.
    Credential IDs
  1. Enter the following command. (Replace MY-ACCESS-TOKEN with your actual access token):
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ 
    --header "Content-Type: application/json" \ 
    --header "Authorization: Bearer MY-ACCESS-TOKEN" \ 
    --data-raw "{}"

    If using an eseal certificate (document signing certificate with only organization information; included with your free esigner.com account), then include “clientData”: “DS_ESEAL” (note: eseals do not require OTP authentication). Other options for “clientData” are “EVCS” for EV Code Signing and “DS” (default) for IV or IV+OV Document Signing :

    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer MY-ACCESS-TOKEN" \
    --data-raw '{"clientData": "DS_ESEAL"}'
  2. You should receive a JSON object with a list of credential IDs associated with the user. Your list will probably contain one value. Copy and paste your credential ID into a text editor for use in later requests.
    Credential IDs

CSC Credentials Info (Optional)

The CSC Credentials Info request will return certificates and other information associated with a credential ID, and is not required for signing.

Postman InstructionscURL Instructions
  1. To use this request, select CSC Credentials Info from the collection and click the Authorization tab.
    authorization tab
  2. Choose Bearer Token from the Type menu, then paste your access token into the Token field.
    Paste token
  3. Select the Body tab, then paste your credential ID as the value for credentialID.
    Paste credential ID
  4. Click the Send button.
    Send
  5. A JSON object with your signing certificate chain and other information will appear in the Response field.
    Credentials info
  1. Enter the following command. Replace MY-ACCESS-TOKEN and MY-CREDENTIAL-ID with your actual information:
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ 
    --header "Content-Type: application/json" \ 
    --header "Authorization: Bearer MY-ACCESS-TOKEN" \ 
    --data-raw '{ 
    "credentialID": "MY-CREDENTIAL-ID", 
    "certificates": "chain", 
    "certInfo": true, 
    "authInfo": true 
    }'
  2. You should receive a JSON object with your signing certificate chain and other information:
    CSC Credentials Info

Credentials Authorize

The Credentials Authorize request will retrieve authorization for signing a hash.

Postman InstructionscURL Instructions
  1. Begin by selecting Credentials Authorize from the collection and clicking the Authorization tab.
    Authorization tab
  2. Choose Bearer Token from the Type menu, then paste your access token into the Token field.
    paste token
  3. Select the Body tab. Paste your credential ID as the credentialID value and a hash of the document you wish to sign as the hash value. Retrieve and enter an OTP from your authentication app and enter it as the value for OTP, then click the Send button. Note: OTP is not required for esealing certificates.
    Body tab
  4. A JSON object with your Signature Activation Data (SAD) will appear in the Response field. Copy and paste this value into a text editor for use in the hash signing request.
    SAD
  1. Use the following command. Replace MY-ACCESS-TOKEN, MY-CREDENTIAL-ID, and MY-HASH with your actual information. Get a one-time password from your 2FA application and use is as the value for MY-OTP. Note: OTP is not required for esealing certificates.
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ 
    --header "Content-Type: application/json" \ 
    --header "Authorization: Bearer MY-ACCESS-TOKEN" \ 
    --data-raw '{ 
        "credentialID": "MY-CREDENTIAL-ID", 
        "numSignatures": 1, 
        "hash": [
            "MY-HASH"
        ],
        "OTP": "MY-OTP"
    }'
  2. You should receive a JSON object with your Signature Activation Data (SAD). Copy and paste this value into a text editor for use in the hash signing request.
    Credentials Authorize

Sign Hash

Now you’re ready to sign the document hash.

Postman InstructionscURL Instructions
  1. Select Sign Hash from the collection, then select the Authorization tab.
    Authorization tab
  2. Choose Bearer Token from the Type menu, then paste your access token into the Token field.
    Paste token
  3. Select the Body tab. Paste your credential ID as the credentialID value, your Signature Activation Data as the SAD value, and a hash of the document you wish to sign as the hash value, then click the Send button.
    Body tab
  4. A JSON object with your signature will appear in the Response field.
    Signature
  1. Enter the following command. Replace MY-ACCESS-TOKENMY-CREDENTIAL-ID, MY-SAD, and MY-HASH with your actual information:
    curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ 
    --header "Content-Type: application/json" \ 
    --header "Authorization: Bearer MY-ACCESS-TOKEN" \ 
    --data-raw '{ 
        "credentialID": "MY-CREDENTIAL-ID", 
        "SAD": "MY-SAD", 
        "hash": [ "MY-HASH" ], 
        "signAlgo": "1.2.840.113549.1.1.11" 
    }'
  2. You should receive a JSON object containing your signature.
    Sign hash

Sign a PDF

In addition to signing document hashes, you can also upload and sign a PDF file.

When signing a PDF you will be working with two POST requests:

  • Upload PDF Document
  • Sign PDF Document

Document Signing API Collection

You can re-use the credential you retrieved above with the CSC Credentials List request. You will probably also need to retrieve a new access token.

Upload PDF Document

Postman InstructionscURL Instructions
  1. Select the Upload PDF Document request and click the Authorization tab.
    Authorization tab
  2. Choose Bearer Token from the Type menu, then paste your access token into the Token field.
    Paste token
  3. Select the Headers tab and paste your credential ID in the Value column.
    Headers tab
  4. Select the Body tab and click the × next to hello.pdf to remove this placeholder filename.
    remove example filename
  5. Click the Select File button, then navigate to the file you want to upload.
    Select file
  6. Click the Send button.
    Send
  7. Select and copy the id value in the response to use in the next request.
    ID
  1. Use the following command. Replace MY-CREDENTIAL-ID, MY-ACCESS-TOKEN, and /PATH/TO/FILE.pdf with your actual information:
    curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ 
    --header "Credential-Id: MY-CREDENTIAL-ID" \ 
    --header "Authorization: Bearer MY-ACCESS-TOKEN" \ 
    --header "Content-Type: application/pdf" \ 
    --data-binary "@/PATH/TO/FILE.pdf"
  2. You will receive a JSON object with a value for id. Copy this value to use in the next request.
    Upload PDF

Note: For visible signatures, please refer to the following HTTP Request Headers (/v1/pdf/upload):

Request Header

Description

Credential-Id

Unique Credential ID assigned to the key – Mandatory

Signing-Reason

Add signing reason to add in signature appearance and also in signature dictionary – Optional e.g. I approve this document

Signing-Location

Add signing location in signature dictionary – Optional e.g. Houston, Texas

Contact-Info

Add contact information in signature dictionary – Optional e.g. Phone number

Signature-Field-Position

Signature field position where visual signature displays. The format is “x,y,width,height“ – Optional

Page-Number

Page number where to draw signature – Optional, in eSigner CSC API, page number starts from zero (0)

Hand-Signature

Base64 encoded PNG image of hand signature – Optional


Sign PDF Document

Now you can sign the PDF.

OTP authorization is not required when signing using an eSealing document signing certificate. Ignore all OTP parameters in the following guide if using an esealing document signing cerificate.
Postman InstructionscURL Instructions
  1. Select the Upload PDF Document request and click the Authorization tab.
       Authorization
  2. Choose Bearer Token from the Type menu, then paste your access token into the Token field.
    Paste token
  3. Select the Body tab, paste in the id value from the previous step and an OTP from your authentication app, then click the Send button.
    Send request
  4. The PDF data will appear below in the Response field. Choose Save to a File from the Save Response menu, then give the file a name.
    Save PDF to File
  5. Open the file in Acrobat to confirm that the file has been signed.
    Valid Signature
  1. Enter the following command. Replace MY-CREDENTIAL-ID, MY-FILE-ID, and OUTPUT-FILENAME with your actual information. Get a one-time password (OTP) from your 2FA app and enter it as MY-OTP. Note: OTP is not required for esealing certificates:
    curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \
    --header 'Content-Transfer-Encoding: application/json' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer MY-ACCESS-TOKEN' \
    --data-raw '{ 
        "id": "MY-FILE-ID", 
        "otp":"MY-OTP" 
    }' \
    --output OUTPUT-FILENAME
  2. cURL will download the signed file and save it to the filename you specified:
    Sign PDF
  3. Open the PDF in Acrobat or Acrobat Reader to check that the signature is valid.
    Valid signature

SSL.com’s Document Signing Certificates are trusted worldwide to digitally sign and certify Adobe PDF and Microsoft Office documents with secure digital signatures. 

BUY YOUR SSL.COM DOCUMENT SIGNING CERTIFICATE

Check out the pricing guide for eSigner Document Signing

SEE PRICING TIERS

Testing Remote Document Signing with eSigner CSC API in the Sandbox

This section covers use of the CSC API in SSL.com’s Sandbox testing environment, so you can feel free to experiment with the API without worrying about getting billed. Please refer to our Sandbox guide for instructions on setting up your Sandbox account.

Create a Test Order

If you’d like to skip creating a Sandbox account and test order, you can also try the eSigner Sandbox with a demo account and certificate. Please read eSigner Demo Credentials and Certificates for credentials and configuration information.
  1. First, you’ll need to create a document signing order in the Sandbox. Begin by signing into your Sandbox account and going to the Dashboard tab.
    Sandbox Dashboard
  2. Click developer tools.
    developer tools
  3. Select eSigner Document Signing, then click the Create Test Order button.
  4. A dialog box will appear. Click the OK button.
  5. Locate your test order, then click the details link.
    details link
  6. Click edit registrant to begin entering applicant and recipient information for your test order. Note that since this information will not be used to issue a valid document signing certificate, you can enter fictitious information if desired.
    edit registrant
  7. Add applicant information for the test certificate, then click the Next>> button.
    Applicant Information
  8. Enter recipient information, then click the Next>> button.
    recipient information
  9. Click the Skip button to skip uploading validation documents for the test certificate.
    Skip button
  10. Your test order should now have a status of pending validation. Contact the SSL.com support team at Support@SSL.com to have your test certificate validated.
    pending validation

Enroll in eSigner and Set Up Two-Factor Authentication

Follow the same instructions for this process as in the production mode.

Install Postman and Import CSC API Collection

  1. Download and unzip the CSC API Postman collection (see https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation for the latest api endpoints or collection downloads).
    CSC API Postman Collection
  2. Download and install the Postman REST Client.
    Postman REST Client download
  3. Launch Postman, then create a new Postman account or sign into an existing one.
    Postman Login
  4. Click the Import button.
    Import button
  5. Click the Upload Files button, navigate to the unzipped API collection file (CSC-API.postman_collection.json), and open it.
    Upload Files
  6. Click the Import button.
    Import button
  7. Click the Collections tab in Postman and expand the CSC API collection to view the five POST requests you will be working with:
    • CSC Info
    • CSC Credentials List
    • CSC Credentials Info
    • Credentials Authorize
    • Sign Hash

    CSC API Collection

Retrieve Access Token

  1. The next step is to retrieve an access token from SSL.com. Before you request your access token, you will need a Client ID (also known as an Application ID. Please refer to this how-to for instructions on generating this credential).
  2. Select the Authorization tab, select OAuth 2.0 from the Type menu, and click the Get New Access Token button.
    Get New Access Token
  3. Enter the following information into the form:
    • Token Name: SandBox CSC (or any other easy-to-remember name that you prefer)
    • Grant Type: Authorization Code
    • Callback URL: [leave blank]
    • Authorize using browser: checked
    • Auth URL: https://oauth-sandbox.ssl.com/oauth2/authorize
    • Access Token URL: https://oauth-sandbox.ssl.com/oauth2/token
    • Client ID: [Your Client ID]
    • Client Secret: [Your Client Secret]
    • Scope: service
    • State: [leave blank]
    • Client Authentication: Send as Basic Auth header

    When you are finished, click the Request Token button.
    Get new access token

  4. A login form will appear in your web browser. Enter your SSL.com username and password, then click the Member Login button.
    Account Login Form
  5. Your new access token should appear in Postman. Select the access token text and copy it to the clipboard, then close the Manage Access Tokens dialog box. Paste your access token into a text editor where you can access it easily. Each access token will expire after one hour.
    You can also save your token for re-use in Postman requests, but we have found that it is most reliable to copy and paste the token directly into each request.
    Access Token

Sign a Hash

Now that you have an access token, you can begin making API requests and creating signatures. This section will lead you through the five available requests in the Postman CSC collection, resulting in the creation of a digital signature from a document hash.

Get CSC Info (Optional)

  1. You can use the CSC Info request to get information about SSL.com’s cloud signature service. Note that, unlike the others in the collection, this request does not require your access token. To send the request, select CSC Info from the CSC API collection, then click the Send button.
    CSC Info Request
  2. Information about the cloud signature service will appear in a JSON object in Postman’s Response field.
    CSC Info
cURL Command
curl --location --request POST "https://cs-try.ssl.com/csc/v0/info" \
--header "Content-Type: application/json" \
--data-raw "{}"

CSC Credentials List

  1. The CSC Credentials List request will retrieve a credential you will use in later API requests. Select CSC Credentials List and click the Authorization tab.
    CSC Credentials List
  2. Choose Bearer Token from the Type menu, paste your access token into the Token field, then click the Send button.
    Add token and send request
  3. A JSON object with a list of credential IDs associated with the user will appear in the Response field. Your list will probably contain one value. Copy and paste your credential ID into a text editor for use in later requests.
    Credential ID
cURL Command

Replace MY-ACCESS-TOKEN with your actual access token:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer MY-ACCESS-TOKEN" \
--data-raw "{}"

If using an eseal certificate (document signing certificate with only organization information; included with your free esigner.com account), then include “clientData”: “DS_ESEAL” (note: eseals do not require OTP authentication). Other options for “clientData” are “EVCS” for EV Code Signing and “DS” (default) for IV or IV+OV Document Signing :

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer MY-ACCESS-TOKEN" \
--data-raw "{\"clientData\": \"DS_ESEAL\"}"

CSC Credentials Info (Optional)

  1. The CSC Credentials Info request will return certificates and other information associated with a credential ID, and is not required for signing. To use this request, select CSC Credentials Info from the collection and click the Authorization tab.
    CSC Credentials Info
  2. Choose Bearer Token from the Type menu, then paste your access token into the Token field.
    paste authorization token
  3. Select the Body tab, then paste your credential ID as the value for credentialID.
    Enter credential ID
  4. Click the Send button.
    Click send button
  5. A JSON object with your signing certificate chain and other information will appear in the Response field.
    Credential ID info
cURL Command

Replace MY-ACCESS-TOKEN and MY-CREDENTIAL-ID with your actual information:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/info" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer MY-ACCESS-TOKEN" \
--data-raw "{
\"credentialID\": \"MY-CREDENTIAL-ID\",
\"certificates\": \"chain\",
\"certInfo\": true,
\"authInfo\": true
}"

Credentials Authorize

  1. The Credentials Authorize request will retrieve authorization for signing a hash. Begin by selecting Credentials Authorize from the collection and clicking the Authorization tab.
    Credentials Authorize
  2. Choose Bearer Token from the Type menu, then paste your access token into the Token field.
    paste token
  3. Select the Body tab. Paste your credential ID as the credentialID value and a hash of the document you wish to sign as the hash value. Retrieve and enter an OTP from your authentication app and enter it as the value for OTP, then click the Send button.
    enter credential id, hash, and OTP
  4. A JSON object with your Signature Activation Data (SAD) will appear in the Response field. Copy and paste this value into a text editor for use in the hash signing request.
    SAD
cURL Command

Replace MY-ACCESS-TOKENMY-CREDENTIAL-ID, MY-HASH, and MY-OTP with your actual information:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/authorize" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer MY-ACCESS-TOKEN" \
--data-raw "{
    \"credentialID\": \"MY-CREDENTIAL-ID\",
    \"numSignatures\": 1,
    \"hash\": [
        \"MY-HASH\"
    ],    
    \"OTP\": \"MY-OTP\"
}"

Sign Hash

  1. Now we’re ready to sign the document hash. Select Sign Hash from the collection, then select the Authorization tab.
    Sign Hash
  2. Choose Bearer Token from the Type menu, then paste your access token into the Token field.
    paste token
  3. Select the Body tab. Paste your credential ID as the credentialID value, your Signature Activation Data as the SAD value, and a hash of the document you wish to sign as the hash value, then click the Send button.
    Paste SAD and hash, send request
  4. A JSON object with your signature will appear in the Response field.
    signature
cURL Command

Replace MY-ACCESS-TOKENMY-CREDENTIAL-ID, MY-SAD, and MY-HASH with your actual information:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/signatures/signHash" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer MY-ACCESS-TOKEN" \
--data-raw "{
    \"credentialID\": \"MY-CREDENTIAL-ID\",
    \"SAD\": \"MY-SAD\",
    \"hash\": [
        \"MY-HASH\"
    ],    
    \"signAlgo\": \"1.2.840.113549.1.1.11\"
}"

Sign a PDF

In addition to signing document hashes, you can also upload and sign a PDF file. Begin by downloading and importing the Document Signing API Postman collection (see https://www.postman.com/sslcom/workspace/public/collection/3454644-277d8427-f749-4a94-93bf-c3478b79b999?ctx=documentation for the latest api endpoints and collection downloads), following the same installation steps you followed above for the CSC API collection.

OTP authorization is not required when signing using an esealing document signing certificate. Ignore all OTP parameters in the following guide if using an esealing document signing cerificate.
When signing a PDF you will be working with two POST requests:

  • Upload PDF Document
  • Sign PDF Document

Document Signing API Collection

You can re-use the credential you retrieved above with the CSC Credentials List request. You will probably also need to retrieve a new access token.

Upload PDF Document

  1. Select the Upload PDF Document request and click the Authorization tab.
    Upload PDF Document
  2. Choose Bearer Token from the Type menu, then paste your access token into the Token field.
    Paste token
  3. Select the Headers tab and paste your credential ID in the Value column.
    add credential ID to header
  4. Select the Body tab and click the × next to hello.pdf to remove this placeholder filename.
    remove placeholder file
  5. Click the Select File button, then navigate to the file you want to upload.
    Select File
  6. Click the Send button.
    Send request
  7. Select and copy the id value in the response to use in the next request.
    file ID

cURL command

Replace MY-CREDENTIAL-ID, MY-ACCESS-TOKEN, and /PATH/TO/FILE.pdf with your actual information:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/upload" \
--header "Credential-Id: MY-CREDENTIAL-ID" \
--header "Authorization: Bearer MY-ACCESS-TOKEN" \
--header "Content-Type: application/pdf" \
--data-binary "@/PATH/TO/FILE.pdf"

Note: For visible signatures, please refer to the following HTTP Request Headers (/v1/pdf/upload):

Request Header

Description

Credential-Id

Unique Credential ID assigned to the key – Mandatory

Signing-Reason

Add signing reason to add in signature appearance and also in signature dictionary – Optional e.g. I approve this document

Signing-Location

Add signing location in signature dictionary – Optional e.g. Houston, Texas

Contact-Info

Add contact information in signature dictionary – Optional e.g. Phone number

Signature-Field-Position

Signature field position where visual signature displays. The format is “x,y,width,height“ – Optional

Page-Number

Page number where to draw signature – Optional

Hand-Signature

Base64 encoded PNG image of hand signature – Optional




Sign PDF Document

  1. Now you can sign the PDF. Select the Upload PDF Document request and click the Authorization tab.
      
  2. Choose Bearer Token from the Type menu, then paste your access token into the Token field.
    paste token
  3. Select the Body tab, and paste in the id value from the previous step.
    enter ID
  4. Enter an OTP from your authentication app and click the Send button.
    enter OTP and click Send
  5. The PDF data will appear below in the Response field. Choose Save to a File from the Save Response menu, then give the file a name.
    Save to a file
  6. Open the file in Acrobat to confirm that the file has been signed. (Note that in the screenshot below, SSL.com’s RSA Development root has been manually trusted in Acrobat.)
    digital signature in Adobe Acrobat

cURL Command

Replace MY-CREDENTIAL-ID, MY-FILE-ID, and MY-OTP with your actual information:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/sign" \
--header "Content-Transfer-Encoding: application/json" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer MY-ACCESS-TOKEN" \
--data-raw "{
    \"id\": \"MY-FILE-ID\",
    \"otp\":\"MY-OTP\"
}"

Going Live With Production

To go live, you need to remove “-try” from the subdomain. For instance, to go live with ds-try.ssl.com, remove “-try” so the subdomain will become ds.ssl.com.

Manual Configure Trust in Adobe Acrobat

When using a test certificate to digitally sign a PDF file from Adobe Acrobat, the digital signature will not immediately appear as valid. For a guide on how to manually configure trust of a test document signing certificate in Adobe Acrobat, please read our article: Manual Configure Trust in Adobe Acrobat

SSL.com’s Document Signing Certificates are trusted worldwide to digitally sign and certify Adobe PDF and Microsoft Office documents with secure digital signatures. 

BUY YOUR SSL.COM DOCUMENT SIGNING CERTIFICATE

Check out the pricing guide for eSigner Document Signing

SEE PRICING TIERS

Twitter
Facebook
LinkedIn
Reddit
Email