Order Document Signing for Organization

11 minute read

POST https://www.digicert.com/services/v2/order/certificate/ds_org

Use this endpoint to order a Document Signing for Organization certificate.

Document Signing for Organization certificate is issued to a team or a department within an organization (rather than an individual) to apply electronic signatures, certifying the document’s origin, authenticity, and integrity. DigiCert document signing certificates are compatible with Adobe Acrobat, DocuSign, Microsoft Office, OpenOffice, and LibreOffice documents.

Example requests and responses

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/ds_org' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": { 
        "signature_hash": "sha256",
        "usage_designation": {
            "primary_usage": "signing",
            "additional_usages": [
                "adobe_authentic_documents_trust",
                "ms_document_signing",
                "document_signing"
            ]
        }       
    },
    "cs_provisioning_method": "ship_token",
    "ship_info": {
      "name": "John Doe",
      "addr1": "360 Taylor Street",
      "addr2": "Floor 74",
      "city": "Richmond",
      "state": "va",
      "zip": "69662",
      "country": "us",
      "method": "EXPEDITED"
    },
    "organization": {
        "id": "2022869",
        "contacts": [
            {
                "id": 4532226,
                "first_name": "John",
                "last_name": "Doe",
                "email": "john.doe@digicert.com",
                "job_title": "Analyst",
                "telephone": "+1 1234567890",
                "contact_type": "organization_contact",
                "user_id": 1532529,
                "type": "existing_contact"
            },
            {                
                "first_name": "Doe",
                "last_name": "John",
                "email": "doe.john@digicert.com",
                "job_title": "Analyst",
                "telephone": "+1 1234547860",   
                "contact_type": "technical_contact",     
                "user_id": 1562224,
                "type": "existing_contact"
            }
        ]
    },    
    "custom_renewal_message": "Renew me",
    "additional_emails": [
		"jill.valentine@example.com",
		"leon.kennedy@example.com"
     ],
    "order_validity": {  
        "years": 1    
    },
    "payment_method": "balance",
}

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/ds_org' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {      
        "signature_hash": "sha256",
        "usage_designation": {
            "primary_usage": "signing",
            "additional_usages": [
                "adobe_authentic_documents_trust",
                "ms_document_signing",
                "document_signing"
            ]
        }
    },
    "cs_provisioning_method": "client_app",
    "organization": {
        "id": "2022869",
        "contacts": [
            {
                "id": 4532226,
                "first_name": "John",
                "last_name": "Doe",
                "email": "john.doe@digicert.com",
                "job_title": "Analyst",
                "telephone": "+1 1234567890",
                "contact_type": "organization_contact",
                "user_id": 1532529,
                "type": "existing_contact"
            },
            {                
                "first_name": "Doe",
                "last_name": "John",
                "email": "doe.john@digicert.com",
                "job_title": "Analyst",
                "telephone": "+1 1234547860",   
                "contact_type": "technical_contact",     
                "user_id": 1562224,
                "type": "existing_contact"
            }
        ]
    },    
    "custom_renewal_message": "Renew me",
    "additional_emails": [
		"jill.valentine@example.com",
		"leon.kennedy@example.com"
     ],
    "order_validity": {  
        "years": 1    
    },
    "payment_method": "balance",
}

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/ds_org' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "csr": "-----BEGIN CERTIFICATE REQUEST-----MIIEqTCCApECAQAyZDELMAkGA1UEBhMCVVMxHTAbBgNVBAMMFHd3dy5zb21lLXdlYnNpdGUuY29tMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQCUBYwM76ZC3zE1y9duwkpXeHPuwaoIQ2vrEA2EdcmuaCjAVf23misrlGkw2UBmX1TXnORtweidjN56A+K0QJpsLDFlpwFarEUTC1DAVOsKnbirBaIM5gaHcjtVjVW0Ov08qWHyrJ09\\\/9YbP27aBhtSO9bLjLKvWtu40IsgGFPHy9bGo91kyfUGWWXZlbFWdPD1CeNBhIbx+5r4ckTn8m+qwZQ5U+SrauTeoKrLMs690Wc9bslxstuSMIQmuTfLK9cJXIaeoOfHKC7jDbFmyhuc4A4QJoF+cfkQcj74y8rNmYYNrFycvTV12zY6TUHO+frB+3SuamIhAs3AxdaqEIHkRkdSEj7vg4WF9vpcB0oHmxaScOGRBjlRG\\\/CIXwojhkHKBnYSgRCZU1ZR2XJjnXTnhxh79h5wyvTxciV8SuIytc\\\/EGGTcGQrTpKmwf9CW5A0\\\/33mKrwAeLS8LjBr+6umNqhOn\\\/i8Wc+\\\/UAimM\\\/dNDJhpKuahV\\\/O71zZfdq6BAMXzovDMx7aLoUEetGuGefCnR\\\/HDLs57\\\/aMpQtnE4GTOWfue5Gy0Hq+YGFf\\\/IDOWPNODKuT4kZxsk5GQm\\\/x3KjvuQI9pNDglsFkBG2IqGFP7yYR\\\/QTNW19z9LajPLP5\\\/6gE5z6\\\/oE5u17A2jPpbbtIzuLj+XbT\\\/P3+T+5sjz5iwzmCQIDAQABoAAwDQYJKoZIhvcNAQELBQADggIBAGy5p9ANTVImYf47GDWx4C+lgdyFfDXsbvgE6jVUWwBkVjustcElfFAyQhgCWcrQ4pEZjqvLqJmIcNIfdehnphYP7Tlh0ieAmVFIDfVvjsvRZgOlhmgThxU\\\/B9QkVdtKi5OMEmXzmQKR\\\/tR\\\/hROFw\\\/\\\/U8TylGCpCLDxCBdavoX0tXcETKoCTs\\\/wIXOR\\\/q5mIoyfhsrnnxRZKfCuUPEaiD6LpciZ0yazdvs927i8tXatCJ9KVG48P3rrjbELb01VXdnNMjfUKofVaTAIjKrLgTbxjcIHdbcqiPugtsvWMkFSSVoi5R\\\/ic9ViMFUFsvNA+I8smUbzT+9k8Fw2rcvkjBtljgyg1cd+Anq5zJdxwkiPWcNRjID1HmU859tQ4lsP8mLv1K2RnvKJl+jygXVKi5cVyaP0Fncu1h4CVPJAK8k1wbZXbWJcC8VS1VG1qPpA2TdwB\\\/eXF89UdFTus+7ab4JiY2dj2UQ59sPk0HfRLNOzb9u\\\/Jh0QhT+vhd8B4lCgCpAxM9G4gzziZ1gc\\\/+mxkNIkb\\\/DTwXu4ZIV6HoXOI8Zv05iaxSRUzCYbwnmrmi4jucEtPEpo6INoETzSzwEMfuJiIet9nDdY5D0DQ8AM86W5ow8ajw38BdmDfpD9vmawO8zG6h\\\/MnTKZFU6SIeGHAU4JzkIIHrEqhZP+ELM7OUUV5-----END CERTIFICATE REQUEST-----",
        "key_size": 2048,
        "csr_key_type": rsa,
        "signature_hash": "sha256",
        "usage_designation": {
            "primary_usage": "signing",
            "additional_usages": [
                "adobe_authentic_documents_trust",
                "ms_document_signing",
                "document_signing"
            ]
        }
    },
    "cs_provisioning_method": "email",
    "organization": {
        "id": "2022869",
        "contacts": [
            {
                "id": 4532226,
                "first_name": "John",
                "last_name": "Doe",
                "email": "john.doe@digicert.com",
                "job_title": "Analyst",
                "telephone": "+1 1234567890",
                "contact_type": "organization_contact",
                "user_id": 1532529,
                "type": "existing_contact"
            },
            {                
                "first_name": "Doe",
                "last_name": "John",
                "email": "doe.john@digicert.com",
                "job_title": "Analyst",
                "telephone": "+1 1234547860",   
                "contact_type": "technical_contact",     
                "user_id": 1562224,
                "type": "existing_contact"
            }
        ]
    },    
    "custom_renewal_message": "Renew me",
    "additional_emails": [
		"jill.valentine@example.com",
		"leon.kennedy@example.com"
     ],
    "order_validity": {  
        "years": 1    
    },
    "payment_method": "balance",
}

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "pending"
    }
  ]
}

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "submitted"
    }
  ]
}

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "approved"
    }
  ],  
  "certificate_id": 113
}

{
  "id": 112233,  
  "certificate_id": 845166333113
}

Request parameters

Name	Req/Opt	Type	Description
certificate	required	object	Certificate details.
.. server_platform	optional	object	Server platform type. Default:-1 (other)
.. .. id	required	int	Server platform ID. See Glossary – Server platforms.
.. ca_cert_id	optional	string	ID of the intermediate certificate authority (ICA) certificate to select as the issuing certificate. To get the `ca_cert_id` value for an ICA, use the Product list](/certcentral-apis/services-api/products/product-list.html) endpoint. Account administrators can customize the default and allowed ICAs for each product at the container or user role level. If you do not provide a value for this parameter, we issue the certificate using the default ICA. If you provide the `ca_cert_id` value for an ICA that is not allowed, the request returns an error^. To see the custom ICA settings for each product, use the Product limits endpoint. This parameter is ignored if the option for ICA selection is not enabled for your account. For more information, see[Configure the ICA certificate chain feature for your public TLS certificates.
.. usage_designation	required	object	Object that determines the primary use (KU) and additional uses (EKU) for the certificate.
.. .. primary_usage	required	string	Primary use for the certificate. Allowed values:`signing`
.. .. additional_usages	optional	array	List of additional certificate uses. Default:document_signing Allowed values: `adobe_authentic_documents_trustsigning`, `ms_document_signing`, or `document_signing`.
cs_provisioning_method	required	string	Specify how you want to receive the token. Default:email Allowed values: `email`, `ship_token`, or `client_app`. For more information about the provisioning methods, see Glossary – Provisioning methods After placing the order, go to the Order your Document Signing for Organization certificate page in the CertCentral platform documentation, and view the What’s next subsection to carry out the subsequent tasks.
ship_info	optional	object	For orders with the `cs_provisioning_method` of `ship_token`, specify the shipping address for the hardware token.
.. name	required	string	First and last name of the recipient of the order.
.. addr1	required	string	Shipping address for the token.
.. addr2	required	string	Continuation of street address.
.. city	required	string	Shipping city.
.. state	required	string	Shipping state.
.. zip	required	string	Shipping postal code.
.. country	required	string	Shipping country.
.. method	required	string	Shipping priority for the token. Allowed values: STANDARD or EXPEDITED (incurs additional cost).
.. csr	conditional	string	Certificate signing request (CSR) or public key in PEM format. Format the CSR/public key as a base64-encoded string without line breaks or escape characters. Include the PEM headers and footers (such as `-----BEGIN CERTIFICATE REQUEST-----...` and `...-----END CERTIFICATE REQUEST-----`). For more information about generating a CSR, see Create a CSR. Required if the `cs_provisioning_method` is `email`. After placing the order, if the status of the order is `pending`, you can use the Update CSR endpoint to update the CSR. To check the status of the order, use the Order validation status endpoint. Note: The Services API does not extract information from the CSR to fill in the details of a certificate request.
.. key_size	optional	int	Number of bits used in the key. Default: 2048 Allowed values for RSA key type: 2048, 3072, or 4096. Allowed values for ECC key type: p-256 or p-354.
.. csr_key_type	optional	string	Key type for the CSR. Default: RSA Allowed values: rsa or ecc.
.. signature_hash	optional	string	Hash algorithm used for signing the certificate. Default:`sha-256` Allowed values:: `sha256`, `sha384`, `sha512`.
comments	optional	string	Comments about the order for the administrator or approver reviewing the order request. The comments value is stored on the order request. If the order skips the approval step (skip_approval is set to true), any provided comments value is ignored since CertCentral creates the order directly without creating a corresponding request.
organization	required	object	Object with information about the organization to associate with the request. You can associate the request with an existing organization, or you can create a new organization when you submit the order request. To associate the request with an existing organization, pass the ID of the organization as the value of `organization.id` in the body of your request. To create a new organization, include the details of the organization in the `organization` object. For more information about the structure and required parameters of the `organization` object, see the Create organization documentation. Note: When you submit an order with organization details instead of providing an organization ID, we check the organizations that already exist in your account to avoid creating a duplicate. To override this behavior and force the request to create a new organization, set the `organization.skip_duplicate_org_check` parameter to `true` in the body of your request. Important: When you want to associate an order with an existing organization, we recommend always using the ID of the organization instead of the organization’s details in the body of your request. To get the ID values for organizations in your account, use the List organizations endpoint. Additionally, we recommend deactivating unused organizations to ensure they are never accidentally assigned to a new order request. To deactivate an organization, use the Deactivate organization endpoint.
.. id	required^*	int	The ID of an existing organization to associate with the order. To get the ID of organizations in your account, use the List organizations endpoint. *Not required if you are creating a new organization with your request.
.. contacts	required	array	List of contacts for the organization.
When creating a new organization:
Providing an organization_contact is conditional. An organization_contact is required if the request is from a service user. If omitted, the organization is created and the authenticated user is used as the organization contact.
Providing a technical_contact is optional. If omitted, the organization is created with no technical contact.
When using an existing organization ID:
Providing an organization_contact and technical_contact is optional. If provided, the new organization and technical contact replace the existing contacts stored on the organization.
Note: By default, DigiCert creates the order with the organization contact and technical contact (if one exists) assigned to the organization on the request. To create the order with a different organization or technical contact than those assigned to the organization, include the organization_contact or technical_contact object at the root of the request payload.
.. ..id	required	integer	Unique ID of the contact within the organization.
.. .. first_name	optional	string	First name of the new contact. Note: Required when omitting user_id. If user_id is not omitted, the specified user’s information will be updated with the new value.
.. .. last_name	optional	string	Last name of the new contact. Note: Required when omitting user_id. If user_id is not omitted, the specified user’s information will be updated with the new value.
.. .. email	optional	string	Email address of the new contact. Note: Required when omitting user_id. If user_id is not omitted, the specified user’s information will be updated with the new value.
.. .. job_title	optional	string	Job title of the new contact. Note: Required when omitting user_id. If user_id is not omitted, the specified user’s information will be updated with the new value.
.. .. telephone	optional	string	Telephone number of the new contact. Note: Required when omitting user_id. If user_id is not omitted, the specified user’s information will be updated with the new value.
.. .. contact_type	required	string	Contact type.
Allowed values: organization_contact, technical_contact, or verified_contact.
Note: This parameter is required when creating a new authorized representative or when using an existing verified contact as an authorized representative.
.. .. user_id	required^*	integer	ID of existing user or contact for the account. *Can be omitted if adding a new contact.
.. container	optional	object	If needed, specify the container the order should be placed under.
.. .. id	required	int	Container ID.
renewal_of_order_id	optional^*	int	If order is a renewal, enter the previous order’s ID. *Renewal orders must include either a renewed_thumbprint or renewal_of_order_id value.
custom_renewal_message	optional	string	Custom message to be included in renewal notifications.
additional_emails	optional	array	Additional email addresses to receive certificate notification emails (for example, certificate issuance, duplicate certificate, and certificate renewals).
user_id_assignments	optional	array	List of User IDs that can manage the order.
csa_agreed_to	required	boolean	Specify if the Certificate Subscriber Agreement (CSA) has been agreed to. Set this parameter to `true` to indicate agreement and `false` for disagreement. Default: true Allowed values: true or false.
promo_code	optional	string	Promotional code for the order.
order_validity	required	object	Defines the validity period of the order. For public TLS/SSL certificates, order validity determines the length of a Multi-year Plan.
.. years	required^*	int	Total number of years the certificate and the order are valid. *Can be replaced by order_validity.days or order_validity.custom_expiration_date. Allowed value: 1, 2, or 3
.. days	optional	int	Total number of days the certificate and the order are valid. Overrides order_validity.years. Max: 1095
.. custom_expiration_date	optional	string	Custom expiration date for the order. Overrides order_validity.days and order_validity.years. Format: dd MMM YYYY (for example, “09 JUN 2025”) Range: Must be within three years of the date you request the order.
payment_method	required	string	Payment method for the order. Allowed values:
credit_card	required (if payment_method is card)	object	Object with information about the credit card charged for the order. Required if `payment_method` is `card`.
.. number	required	string	Credit card number.
.. expiration_month	required	string	Credit card expiration month. Format as a two-digit number between `01` (Jan) and `12` (Dec).
.. expiration_year	required	string	Credit card expiration year. Format as a four-digit number. For example: `2026`
.. cvv	required	string	Card verification value (CVV). Format as a three- or four-digit number. For example: `333` or `4444`
.. cardholder_name	required	string	Cardholder’s first and last name.
.. save_credit_card	optional	null	Specify whether to save the credit card details. `true` for saving the details, `false` for not saving the details, and `null` for not indicating the preference. Allowed Values: true, false, or null.
.. set_as_default	required	string	Set the card as the default payment option or method. To set this card as your default payment method, use `1`. To keep your default payment method, use `0`. Allowed Values: 1 or 0.
billing_address	conditional	object	Object with information about the billing address. Required if `payment_method` is `card`.
.. address	required	string	Billing street address.
.. address2	optional	string	Continuation of street address.
.. city	required	string	Billing city.
.. state	conditional	string	Billing state or province. Optional for some countries.
.. country	required	string	Billing country.
.. zip	conditional	string	Billing zip or postal code. Optional for some countries.

Response parameters

Name	Type	Description
id	int	Order ID.
organization	object	Container for new organization details. Only returned if a new organization was created with the order.
.. id	int	Organization ID for the new organization.
requests	array	Contains information about the request.
.. id	int	Request ID.
.. status	string	Request status. Possible values:pending, submitted, approved, rejected
certificate_id	int	Certificate ID. Returned if request status is approved.

After placing the order, go to the Order your Document Signing for Organization certificate page in the CertCentral platform documentation, and view the What’s next subsection to carry out the subsequent tasks.

Was this page helpful?

Provide feedback