Set issuing entities

The issuing entities feature gives you the possibility, for a single workspace, to send a transaction request on behalf of one of your several:

  • brands
  • buisness units
  • subsidiaries
  • services
  • departments

Consequently, it allows you to customize your participant’s signature process.

Note that you can have a maximum of 20 issuing entities per workspace (excluding the workspace itself).

Create an issuing entity

To create an issunig entity, send a request to POST /v1/issuing-entities, and pass the name (required) and logo arguments:

curl
https://api.alpha.universign.com/v1/issuing-entities \
-d name=MyEntityName
-F logo=@entity_logo
-d sms_short_name=MysmsShortName

The issuing entity name is limited to 200 characters and can’t be modified once the issuing entity created.

The logo has to be in PNG or JPEG format and is limited to a 2MB size and a resolution of 150x48. If the logo has a higher resolution, it will be resized to fit the 150x48 resolution. Note that the logo can’t be modified once the issuing entity created. If you don’t set a logo, the issuing entity will inherit the workspace logo.

You can pass optional paramters:

  • is_default: allows you to use the issuing entity by default to send transaction requests.
  • sender_name_display: allows you define in whose name the transaction is sent. (visit set name display options for more details).
  • lock_sender_name_display: allows you to lock the sender_name_display for a given issuing entity. (visit set name display options for more details).
  • sealer_logo_display: allows you to choose the logo that will display on your sealed document. Accepted values are certificate (universign logo), issuing_entity (issuing entity logo), none (no logo to display). Default value is certificate.

You can customize the layout of the signature page to be in accordance with each issuing entity you create. To do so, set the following arguments:

  • header_background_color: The header background color to be displayed on the signature page.
  • header_text_color: The header text color to be displayed on the signature page.
  • header_steps_color:The steps color to be displayed on the signature page.
  • body_background_color: The body background color to be displayed on the signature page.
  • body_text_color: The body text color to be displayed on the signature page.
  • body_button_background_color: The button color to be displayed on the signature page.
  • body_button_text_color: The button text color to be displayed on the signature page.
  • body_button_border_radius: The button border radius to be displayed on the signature page.
  • body_links_color: The links color to be displayed on the signature page.
  • body_underlined_links: Set to true if you want the links on the signature page to be underlined.

If you don’t set any of the following layout related parameters, the Universign default layout will be used for the signature page.

You can also customize the sms that will be sent on behalf of the issuing entity. To do so, set the follwing arguments:

  • sms_short_name: allows you to define the entity short name you want to display in the customized sms (max 20 characters). Value must not be empty.
  • delete_sms_short_name: allows you to delete the customized sms short name.

Note that you can’t customize the sms for the workspace default entity.

Update an issuing entity

To update an issuing entity, send a request to POST /v1/issuing-entities/{id}:

curl
https://api.alpha.universign.com/v1/issuing-entities/iss_3z" \
-d is_default=true \ 
-d sender_name_display=name_issuing_entity \
-d lock_sender_name_display=true \
-F logo=@new_entity_logo \
-d delete_sms_short_name=true

Note that you can update all arguments execept for the issuing entity name.

Activate/deactivate the worksapce entity

You can activate/deactivate only the workspace entity (i.e the workspace itself that was initially used to send transaction requests before you create any other issuing entities).

If the workspace entity is active, you can use it to create transaction requests. If not, you will need to use another issuing entity of your choice instead.

Note that you can’t deactivate the workspace entity if it is used by default or if no other issuing entities are available within your workspace.

Activate the workspace entity

To activate the workspace entity, send a request to POST /v1/issuing-entities/{id}/activate.

curl
https://api.alpha.universign.com/v1/issuing-entities/iss_5X/activate"

The API returns an issuing-entity object, as follows:

{
  "object" : "issuing_entity",
  "id" : "iss_5X",
  "workspace_entity" : true,
  "name" : "workspace_issuer",
  "sender_name_display" : "name_email_issuing_entity",
  "lock_sender_name_display" : true,
  "default" : false,
  "active" : true,
  "pds_configuration" : {
    "header_background_color" : "#FFFFFF",
    "header_text_color" : "#3B4F63",
    "header_steps_color" : "#0072AF",
    "body_background_color" : "#FFFFFF",
    "body_text_color" : "#3B4F63",
    "body_button_background_color" : "#0072AF",
    "body_button_text_color" : "#FFFFFF",
    "body_button_border_radius" : 24,
    "body_links_color" : "#0072AF",
    "body_underlined_links" : false
  }
}

Deactivate the workspace entity

To deactivate the workspace entity, send a request to POST /v1/issuing-entities/{id}/deactivate.

curl
https://api.alpha.universign.com/v1/issuing-entities/iss_5X/deactivate" \

The API returns an issuing-entity object, as follows:

{
  "object" : "issuing_entity",
  "id" : "iss_3z",
  "workspace_entity" : true,
  "name" : "workspace_issuer",
  "sender_name_display" : "name_email_issuing_entity",
  "lock_sender_name_display" : true,
  "default" : false,
  "active" : false,
  "pds_configuration" : {
    "header_background_color" : "#FFFFFF",
    "header_text_color" : "#3B4F63",
    "header_steps_color" : "#0072AF",
    "body_background_color" : "#FFFFFF",
    "body_text_color" : "#3B4F63",
    "body_button_background_color" : "#0072AF",
    "body_button_text_color" : "#FFFFFF",
    "body_button_border_radius" : 24,
    "body_links_color" : "#0072AF",
    "body_underlined_links" : false
  }
}

Retire an issuing entity

You can retire an issuing entity from your workspace. To do so, send a request to POST /v1/issuing-entities/{id}/retire.

curl
https://api.alpha.universign.com/v1/issuing-entities/iss_3z/retire" \

Note that you can’t retire the workspace issuing entity or any other issuing entity used by default.

The API returns an empty 200 response.

List issuing entities

You can list issuing entities available within your workspace. To do so, send a request to GET /v1/issuing-entities.

You can set optional parameters to filter issuing entities:

  • name: allows you to filter issuing entities by name
  • size: allows you to define the number of issuing entities you want to retrieve, starting from the workspace issuing entity. Maximum is 20.
  • ending_before: Expected value is an issuing entity ID. Use for pagination to return the issuing entities listed before the specified one. Do not pass if you set the starting_after parameter.
  • starting_after: Expected value is an issuing entity ID. Use for pagination to return the issuing entities listed after the specified one. Do not pass if you set the ending_before parameter.
  • only_active: allows you to list only active issuing entities.
  • retired: allows you to list only retired issuing entites.
curl https://api.universign.com/v1/issuing-entities?starting_after=iss_5X&size=5

The API returns the list of issuing entities requested.

Create a transaction with an issuing entity

To create a transaction with an issuing entity, send a request to POST /v1/transactions, and pass the issuing_entity_id argument:

curl
https://api.alpha.universign.com/v1/transactions \
-d issuing_entity_id=iss_3z

Note that if you dont set the issuing_entity_id, the transaction will be sent on behalf of your workspace default issung entity.

Set private mode
← Previous
Set sender name display
Next →
Developer tools
Guides
Services
API reference