Working with Carta’s Draft Issuer API

This document explains how to create issuers using Carta’s Draft Issuer API. See our API Reference for details about Draft Issuer objects.

Creating an issuer

1. Request credentials

After completing our registration process, inform your Carta account executive that you want to create new issuers. We will provide you with a specific login name and password to use when you submit a Create Draft Issuer request. This login is specific to your organization and you will use it only when creating issuers.

2. Obtain an access token

Follow our OAuth workflow to obtain an access token. At step 1, use the login and password we provided.

3. Submit your draft issuer request

The example payload below creates a draft issuer named “XYZ Widget Company” with 1000 authorized shares and 100 certificates.

{
  "draftIssuer": {
    "details": {
      "name": "XYZ Widget Company",
      "countryOfIncorporation": {
        "value": "US"
      },
      "currency": {
        "value": "USD"
      },
      "website": "http://www.example.com/XYZwidget",
      "llc": false,
      "employerIdentificationNumber": "56756",
      "doingBusinessAs": "XYZ Widget",
      "industry": "INFORMATION_TECHNOLOGY",
      "stateOfIncorporation": {
        "value": "US-NY"
      },
      "dateOfIncorporation": {
        "value": "2018-10-31"
      },
      "address": {
        "line1": "123 Main Street",
        "city": "New York",
        "countrySubdivision": {
          "value": "US-NY"
        },
        "country": {
          "value": "US"
        },
        "postalCode": "10010"
      },
      "primaryContact": {
        "name": "Jane Doe",
        "title": "CEO",
        "email": "jane.doe@example.com"
      }
    },
    "shareClass": {
      "prefix": "CS",
      "name": "CommonShares",
      "type": "COMMON",
      "parValue": {
        "value": "0.001"
      },
      "seniority": 1,
      "authorizedShares": 1000,
      "authorizedDate": {
        "value": "2019-01-10"
      },
      "certificates": [
        {
          "quantity": 100,
          "issueDate": {
            "value": "2019-06-16"
          },
          "rule144Date": {
            "value": "2019-06-16"
          },
          "vestingSchedule": {
            "name": "2019 Vesting Schedule",
            "length": 24,
            "terms": "double-trigger",
            "vesting": {
              "frequency": "DAILY",
              "onDay": "SAME"
            },
            "cliff": {
              "cliffPercentage": {
                "value": "0.1"
              },
              "cliffValue": {
                "value": "1"
              },
              "cliffDuration": "YEARS"
            }
          },
          "legend": "Default",
          "pricePerShare": {
            "value": "1.00"
          },
          "cashPaid": {
            "value": "100"
          },
          "accelerationTerms": "double-trigger",
          "stakeholder": {
            "name": "John Smith",
            "email": "john.smith@example.com",
            "relationship": "EXECUTIVE",
            "type": "INDIVIDUAL"
          }
        }
      ]
    }
  }
}

---

NOTE

• The countrySubdivision object must follow the ISO 3116-2 subdivision standard. For US-specific information, see ISO 3166-2:US.
• Create Draft Issuer supports only fully incorporated organizations with a valid Employer Identification Number (EIN).

---

 

If Carta successfully creates the issuer, the API will respond with the HTTP 200 status code and the response will contain an id and resultantIssuerId as well as the objects you submitted (omitted from the example below):

{
    "id": "1234",
    "resultantIssuerId": "4321",
    "details": {
        ...
    },
    ...
}

id corresponds to the newly created issuer. You will use that id to fetch the draftIssuer from the Get Draft Issuer endpoint. You can ignore the resultantIssuerId for now. We may use it for future APIs.

4. Activate the account

After creating the issuer, Carta will send an activation email to the user you specified as primaryContact. If that person already has an account, our email will contain a link to Carta’s login page:

If this is a new user, our email will direct them to Carta’s account activation page:

Note: Our Test environment does not generate email. You can validate a new issuer by calling our Get Draft Issuers endpoint with the id we provided in our response.

5. Followup reminder

After creating a new Issuer, we recommend that you alert your user to check their email and complete the account process, for example with a simple message like “Congratulations! Carta has created your new account and has emailed you information on how to activate it.”

Exploring our API

You can use our API Reference to interactively construct a draft issuer request. As you populate values in the BODY PARAMS fields, the example REQUEST text will update to reflect your changes. In the example below, we have entered “ABC Widgets” for the name object and our documentation site has automatically added the details.name object to the sample request:

Clicking in each field reveals additional information about that field:

Using Carta’s mock service

You can explore our platform without needing your own credentials by submitting requests to our mock service which returns valid, generic responses. Here is the URL to retrieve details on an issuer using our draftIssuer mock service:

https://mock-api.carta.com/v1alpha1/draftIssuers/7

You can use a random string for draftIssuers.id as our mock service ignores that value.

To use the mock service from our API Reference, select the mock-api.carta.com option from the Base URL menu:

The “Try It!” button will then retrieve an example response. Note that you will need to populate the Authentication : Bearer field, but any random string will work, for example “abc”: