Skip to main content
API docs by Redocly

PrimaryBid Commercial API (2.0)

Download OpenAPI specification:Download

PrimaryBid Commercial Integrations API

Offers

Get all offers

Retrieves all accessible PrimaryBid offers.

Authorizations:
primary-bid-api-secretprimary-bid-api-subscription
query Parameters
modifiedAfter
string
Example: modifiedAfter=2020-09-01T12:00:00Z

When specified, only return Offers modified on or after this iso_datetime (aka ISO 8601 format “1994-11-05T13:15:30Z”), where:

  • “T” separates the day (YYYY-MM-DD) from the time (HH:MM:SS).
  • ”Z” represents the Coordinated Universal Time (UTC).
Use of modifiedAfter URI query parameter is the recommended method to poll for the presence of new Offers.

offset
number
Example: offset=20

When specified, it refers to the maximum number of offers that should be returned in a single API response.

For example, if you set the field limit to 10, the API will return a maximum of 10 offers in the response.

Together with the field offset allows retrieving a smaller subset of offers, enabling pagination. By adjusting both the offset and limit values, you can navigate through the complete list of offers in smaller, manageable portions.

limit
number
Example: limit=10

When specified, determines the starting point from which the API should begin returning offers. It is used in conjunction with the field limit to implement pagination. By specifying an offset value, you can retrieve different sets of items in subsequent API calls.

For example, if you set the field offset to 20 and the field limit to 10, the API will return offers starting from the 21st up to the 30th item.

Responses

Response Schema: application/json
Array
id
required
string
offerType
required
string
Enum: "primary_placing" "secondary_placing" "fixed_income" "ipo"

The type of public offering used to raise funds.

offerSubType
required
string
Enum: "company_placing" "investment_trust" "intermediary_offer" "blocks" "fully_marketed_offer" "company_ipo" "investment_trust_ipo" "spac_ipo" "de_spac_ipo" "re_ipo" "corporate_bond" "government_bond"

The subtype of the offer launched to raise capital.

required
object (OfferDetailModel)
required
object (OfferTextModel)
required
object (OfferPricingAndOrderLimitsModel)
required
object (OfferDatesModel)
required
object (OfferIssuerModel)
Response Schema: application/json
error
required
string
message
required
string
validationErrors
Array of strings

Response samples

Content type
application/json
[
  • {
    }
]

Get an offer by its identifier

Authorizations:
primary-bid-api-secretprimary-bid-api-subscription
path Parameters
offerId
required
string

The identifier of the offer to be retrieved

Responses

Response Schema: application/json
id
required
string
offerType
required
string
Enum: "primary_placing" "secondary_placing" "fixed_income" "ipo"

The type of public offering used to raise funds.

offerSubType
required
string
Enum: "company_placing" "investment_trust" "intermediary_offer" "blocks" "fully_marketed_offer" "company_ipo" "investment_trust_ipo" "spac_ipo" "de_spac_ipo" "re_ipo" "corporate_bond" "government_bond"

The subtype of the offer launched to raise capital.

required
object (OfferDetailModel)
required
object (OfferTextModel)
required
object (OfferPricingAndOrderLimitsModel)
required
object (OfferDatesModel)
required
object (OfferIssuerModel)
Response Schema: application/json
error
required
string
message
required
string
validationErrors
Array of strings

Response samples

Content type
application/json
{
  • "id": "string",
  • "offerType": "ipo",
  • "offerSubType": "company_placing",
  • "details": {
    },
  • "textProperties": {
    },
  • "pricingAndOrderLimits": {
    },
  • "dates": {
    },
  • "issuer": {
    }
}

Allocations

Get all allocations

Retrieves all accessible PrimaryBid allocations.

Authorizations:
primary-bid-api-secretprimary-bid-api-subscription

Responses

Response Schema: application/json
Array
offerId
required
string

The id of the Offer

price
required
number

Final price for the Offer

priceCurrency
required
string
Enum: "GBX" "GBP" "EUR" "USD" "NOK" "SEK" "DKK"

Final price currency code

allocationCount
number

The number of allocated subscriptions granted by the issuer. Can be reconciled against the number of subscriptions submitted.

required
Array of objects (OfferAllocationDetailModel)

List of allocations for this Offer

Response Schema: application/json
error
required
string
message
required
string
validationErrors
Array of strings

Response samples

Content type
application/json
[
  • {
    }
]

Get allocations for offer

Gets all allocations by associated offerId mapped to OfferAllocationModel.

Authorizations:
primary-bid-api-secretprimary-bid-api-subscription
path Parameters
offerId
required
string
query Parameters
offset
number
Example: offset=20

When specified, determines the starting point from which the API should begin returning allocations. It is used in conjunction with the field limit to implement pagination. By specifying an offset value, you can retrieve different sets of allocations in subsequent API calls. For example, if you set the field offset to 20 and the field limit to 10, the API will return allocations starting from the 21st up to the 30th item.

limit
number
Example: limit=10

When specified, it refers to the maximum number of allocations that should be returned in a single API response.

For example, if you set the field limit to 10, the API will return a maximum of 10 allocations in the response.

Together with the field offset allows retrieving a smaller subset of allocations, enabling pagination. By adjusting both the offset and limit values, you can navigate through the complete list of allocations in smaller, manageable portions.

Responses

Response Schema: application/json
offerId
required
string

The id of the Offer

price
required
number

Final price for the Offer

priceCurrency
required
string
Enum: "GBX" "GBP" "EUR" "USD" "NOK" "SEK" "DKK"

Final price currency code

allocationCount
number

The number of allocated subscriptions granted by the issuer. Can be reconciled against the number of subscriptions submitted.

required
Array of objects (OfferAllocationDetailModel)

List of allocations for this Offer

Response Schema: application/json
error
required
string
message
required
string
validationErrors
Array of strings

Response samples

Content type
application/json
{
  • "offerId": "string",
  • "price": 0,
  • "priceCurrency": "GBX",
  • "allocationCount": 0,
  • "allocations": [
    ]
}

Subscriptions

Get all subscriptions

Retrieves all accessible PrimaryBid subscriptions.

Authorizations:
primary-bid-api-secretprimary-bid-api-subscription
query Parameters
offerId
string
Example: offerId=8ecd493a-562f-45b3-b1a5-4d05d3eb5f2c

When specified, only returns subscriptions placed on a specific offer id.

offset
number
Example: offset=20

When specified, determines the starting point from which the API should begin returning subscriptions. It is used in conjunction with the field limit to implement pagination. By specifying an offset value, you can retrieve different sets of subscriptions in subsequent API calls. For example, if you set the field offset to 20 and the field limit to 10, the API will return subscriptions starting from the 21st up to the 30th item.

limit
number
Example: limit=10

When specified, it refers to the maximum number of subscriptions that should be returned in a single API response.

For example, if you set the field limit to 10, the API will return a maximum of 10 subscriptions in the response.

Together with the field offset allows retrieving a smaller subset of subscriptions, enabling pagination. By adjusting both the offset and limit values, you can navigate through the complete list of subscriptions in smaller, manageable portions.

Responses

Response Schema: application/json
Array
id
required
string

A unique id generated by PrimaryBid for this subscription.

offerId
required
string

Reference to Offer (returned from GET /offer)

amountRequested
required
number

The cash amount of the subscription requested by the investor in the currency associated with the PrimaryBid API client. This amount should contain no more than 6 decimal places.

clientSubscriptionReference
string

A reference given to PrimaryBid by the API client so that they can tie the subscription back to their records. A unique subscriptionId is additionally generated by PrimaryBid.

currency
required
string
Enum: "GBX" "GBP" "EUR" "USD" "NOK" "SEK" "DKK"

The currency of the cash amount of the subscription requested by the investor as per the currency associated with the PrimaryBid API client.

investorReferenceType
string
Enum: "nino" "lei" "identity_card_number" "passport_number" "concat" "ssn" "other"

Describes the form of the investor reference. nino (National Insurance Number), lei (Legal Entity Identifier), identity_card_number (identification card number), passport_number (passport number), concat (MiFID II investor identifier)

investorReference
string

Investor reference as per investorReferenceType

subscriptionType
required
string
Enum: "xo_qualified" "xo_unqualified" "discretionary_qualified" "discretionary_unqualified" "institutional"

Describes the type of investment based on the profile of the investor: xo_qualified (Execution-only, qualified investor), xo_unqualified (Execution-only, unqualified investor), discretionary_qualified (Discretionary investment, qualified investor), discretionary_unqualified (Discretionary investment, unqualified investor), institutional (Institutional investor)

status
required
string
Enum: "accepted" "rejected" "cancelled"

Information regarding a logged subscription. Status can be either accepted, rejected, or cancelled.

clientSubscriptionTimestamp
required
string <date-time>

The timestamp when the order is received by the API client's client.

Use the ISO 8601 format “1994-11-05T13:15:30Z”, where:

● “T” separates the day (YYYY-MM-DD) from the time (HH:MM:SS).

● ”Z” stands for the UTC standard.

isExistingShareholder
boolean

Is the investor an existing shareholder?

numExistingShares
number

Number of shares investor currently holds

isIssuerEmployee
boolean

Is the investor an employee of the issuer?

membershipCode
string

The access code for community offerings. Investors should have received it from the issuer.

membershipStatus
string
Enum: "verified" "pending_checks" "code_not_found"

When a subscription to a community offering is accepted, PrimaryBid validates the membership code and returns its status which can be either verified or unverified.

subscriptionCategory
string
Enum: "retail" "professional" "ecp/institutional"

The type of investment based on the profile of the investor:

● Retail - demand is coming from a private, unqualified investor;

● Professional - demand is coming from a certified investor;

● Institutional - demand is coming from a corporate investor.

accountType
string
Enum: "general_investment" "tax_efficient"

The financial account category used to fund this subscription. Can be either a general investment account or a tax-efficient account.

Response samples

Content type
application/json
[
  • {
    }
]

Create a new subscription

Creates a new subscription.

Note: Calling the POST/subscription endpoint several times, with identical request bodies, creates multiple records. To prevent data duplication, we suggest setting up some rules at your end.

Authorizations:
primary-bid-api-secretprimary-bid-api-subscription
Request Body schema: application/json
required
offerId
required
string

Reference to Offer (returned from GET /offer)

amountRequested
required
number

The cash amount of the subscription requested by the investor in the currency associated with the PrimaryBid API client. This amount should contain no more than 6 decimal places.

subscriptionType
required
string
Deprecated
Enum: "xo_qualified" "xo_unqualified" "discretionary_qualified" "discretionary_unqualified" "institutional"

Describes the type of investment based on the profile of the investor: xo_qualified (Execution-only, qualified investor), xo_unqualified (Execution-only, unqualified investor), discretionary_qualified (Discretionary investment, qualified investor), discretionary_unqualified (Discretionary investment, unqualified investor), institutional (Institutional investor). If neither subscription type or subscription category are provided, then value will default to 'discretionary_qualified'.

subscriptionCategory
required
string
Enum: "retail" "professional" "ecp/institutional"

Describes the type of investment based on the profile of the investor: retail (Execution-only), professional (Professional investment), Institutional (Institutional investor). If neither subscription type or subscription category are provided, then value will default to 'professional'.

clientSubscriptionTimestamp
required
string <date-time>

The timestamp when the order is received by the API client's client.

Use the ISO 8601 format “1994-11-05T13:15:30Z”, where:

● “T” separates the day (YYYY-MM-DD) from the time (HH:MM:SS).

● ”Z” stands for the UTC standard.

clientSubscriptionReference
string

A reference given to PrimaryBid by the API client so that they can tie the subscription back to their records. A unique subscriptionId is additionally generated by PrimaryBid.

investorReferenceType
string
Enum: "nino" "lei" "identity_card_number" "passport_number" "concat" "ssn" "other"

Describes the form of the investor reference. nino (National Insurance Number), lei (Legal Entity Identifier), identity_card_number (identification card number), passport_number (passport number), concat (MiFID II investor identifier)

investorReference
string

Investor reference as per investorReferenceType

isExistingShareholder
boolean

Is the investor an existing shareholder?

numExistingShares
number

How many existing shares does the shareholder own?

isIssuerEmployee
boolean

Is the investor an employee of the issuer?

currency
required
string
Enum: "GBX" "GBP" "EUR" "USD" "NOK" "SEK" "DKK"

The currency of the cash amount of the subscription requested by the investor as per the currency associated with the PrimaryBid API client.

membershipCode
string

The access code for community offerings. Investors should have received it from the issuer.

accountType
required
string
Enum: "general_investment" "tax_efficient"

The financial account category used to fund this subscription. Can be either a general investment account or a tax-efficient account.

Responses

Response Schema: application/json
id
required
string

A unique id generated by PrimaryBid for this subscription.

offerId
required
string

Reference to Offer (returned from GET /offer)

amountRequested
required
number

The cash amount of the subscription requested by the investor in the currency associated with the PrimaryBid API client. This amount should contain no more than 6 decimal places.

clientSubscriptionReference
string

A reference given to PrimaryBid by the API client so that they can tie the subscription back to their records. A unique subscriptionId is additionally generated by PrimaryBid.

currency
required
string
Enum: "GBX" "GBP" "EUR" "USD" "NOK" "SEK" "DKK"

The currency of the cash amount of the subscription requested by the investor as per the currency associated with the PrimaryBid API client.

investorReferenceType
string
Enum: "nino" "lei" "identity_card_number" "passport_number" "concat" "ssn" "other"

Describes the form of the investor reference. nino (National Insurance Number), lei (Legal Entity Identifier), identity_card_number (identification card number), passport_number (passport number), concat (MiFID II investor identifier)

investorReference
string

Investor reference as per investorReferenceType

subscriptionType
required
string
Enum: "xo_qualified" "xo_unqualified" "discretionary_qualified" "discretionary_unqualified" "institutional"

Describes the type of investment based on the profile of the investor: xo_qualified (Execution-only, qualified investor), xo_unqualified (Execution-only, unqualified investor), discretionary_qualified (Discretionary investment, qualified investor), discretionary_unqualified (Discretionary investment, unqualified investor), institutional (Institutional investor)

status
required
string
Enum: "accepted" "rejected" "cancelled"

Information regarding a logged subscription. Status can be either accepted, rejected, or cancelled.

clientSubscriptionTimestamp
required
string <date-time>

The timestamp when the order is received by the API client's client.

Use the ISO 8601 format “1994-11-05T13:15:30Z”, where:

● “T” separates the day (YYYY-MM-DD) from the time (HH:MM:SS).

● ”Z” stands for the UTC standard.

isExistingShareholder
boolean

Is the investor an existing shareholder?

numExistingShares
number

Number of shares investor currently holds

isIssuerEmployee
boolean

Is the investor an employee of the issuer?

membershipCode
string

The access code for community offerings. Investors should have received it from the issuer.

membershipStatus
string
Enum: "verified" "pending_checks" "code_not_found"

When a subscription to a community offering is accepted, PrimaryBid validates the membership code and returns its status which can be either verified or unverified.

subscriptionCategory
string
Enum: "retail" "professional" "ecp/institutional"

The type of investment based on the profile of the investor:

● Retail - demand is coming from a private, unqualified investor;

● Professional - demand is coming from a certified investor;

● Institutional - demand is coming from a corporate investor.

accountType
string
Enum: "general_investment" "tax_efficient"

The financial account category used to fund this subscription. Can be either a general investment account or a tax-efficient account.

Response Schema: application/json
status
required
number
required
Array of objects (ValidationErrorModel)
message
required
string

Request samples

Content type
application/json
{
  • "offerId": "string",
  • "amountRequested": 0,
  • "subscriptionType": "xo_qualified",
  • "subscriptionCategory": "retail",
  • "clientSubscriptionTimestamp": "2019-08-24T14:15:22Z",
  • "clientSubscriptionReference": "string",
  • "investorReferenceType": "nino",
  • "investorReference": "string",
  • "isExistingShareholder": true,
  • "numExistingShares": 0,
  • "isIssuerEmployee": true,
  • "currency": "GBP",
  • "membershipCode": "string",
  • "accountType": "general_investment"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "offerId": "string",
  • "amountRequested": 0,
  • "clientSubscriptionReference": "string",
  • "currency": "GBX",
  • "investorReferenceType": "nino",
  • "investorReference": "string",
  • "subscriptionType": "xo_qualified",
  • "status": "accepted",
  • "clientSubscriptionTimestamp": "2019-08-24T14:15:22Z",
  • "isExistingShareholder": true,
  • "numExistingShares": 0,
  • "isIssuerEmployee": true,
  • "membershipCode": "string",
  • "membershipStatus": "verified",
  • "subscriptionCategory": "retail",
  • "accountType": "general_investment"
}

Get specific subscription

Gets a subscription by its identifier.

Authorizations:
primary-bid-api-secretprimary-bid-api-subscription
path Parameters
subscriptionId
required
string

Responses

Response Schema: application/json
id
required
string

A unique id generated by PrimaryBid for this subscription.

offerId
required
string

Reference to Offer (returned from GET /offer)

amountRequested
required
number

The cash amount of the subscription requested by the investor in the currency associated with the PrimaryBid API client. This amount should contain no more than 6 decimal places.

clientSubscriptionReference
string

A reference given to PrimaryBid by the API client so that they can tie the subscription back to their records. A unique subscriptionId is additionally generated by PrimaryBid.

currency
required
string
Enum: "GBX" "GBP" "EUR" "USD" "NOK" "SEK" "DKK"

The currency of the cash amount of the subscription requested by the investor as per the currency associated with the PrimaryBid API client.

investorReferenceType
string
Enum: "nino" "lei" "identity_card_number" "passport_number" "concat" "ssn" "other"

Describes the form of the investor reference. nino (National Insurance Number), lei (Legal Entity Identifier), identity_card_number (identification card number), passport_number (passport number), concat (MiFID II investor identifier)

investorReference
string

Investor reference as per investorReferenceType

subscriptionType
required
string
Enum: "xo_qualified" "xo_unqualified" "discretionary_qualified" "discretionary_unqualified" "institutional"

Describes the type of investment based on the profile of the investor: xo_qualified (Execution-only, qualified investor), xo_unqualified (Execution-only, unqualified investor), discretionary_qualified (Discretionary investment, qualified investor), discretionary_unqualified (Discretionary investment, unqualified investor), institutional (Institutional investor)

status
required
string
Enum: "accepted" "rejected" "cancelled"

Information regarding a logged subscription. Status can be either accepted, rejected, or cancelled.

clientSubscriptionTimestamp
required
string <date-time>

The timestamp when the order is received by the API client's client.

Use the ISO 8601 format “1994-11-05T13:15:30Z”, where:

● “T” separates the day (YYYY-MM-DD) from the time (HH:MM:SS).

● ”Z” stands for the UTC standard.

isExistingShareholder
boolean

Is the investor an existing shareholder?

numExistingShares
number

Number of shares investor currently holds

isIssuerEmployee
boolean

Is the investor an employee of the issuer?

membershipCode
string

The access code for community offerings. Investors should have received it from the issuer.

membershipStatus
string
Enum: "verified" "pending_checks" "code_not_found"

When a subscription to a community offering is accepted, PrimaryBid validates the membership code and returns its status which can be either verified or unverified.

subscriptionCategory
string
Enum: "retail" "professional" "ecp/institutional"

The type of investment based on the profile of the investor:

● Retail - demand is coming from a private, unqualified investor;

● Professional - demand is coming from a certified investor;

● Institutional - demand is coming from a corporate investor.

accountType
string
Enum: "general_investment" "tax_efficient"

The financial account category used to fund this subscription. Can be either a general investment account or a tax-efficient account.

Response samples

Content type
application/json
{
  • "id": "string",
  • "offerId": "string",
  • "amountRequested": 0,
  • "clientSubscriptionReference": "string",
  • "currency": "GBX",
  • "investorReferenceType": "nino",
  • "investorReference": "string",
  • "subscriptionType": "xo_qualified",
  • "status": "accepted",
  • "clientSubscriptionTimestamp": "2019-08-24T14:15:22Z",
  • "isExistingShareholder": true,
  • "numExistingShares": 0,
  • "isIssuerEmployee": true,
  • "membershipCode": "string",
  • "membershipStatus": "verified",
  • "subscriptionCategory": "retail",
  • "accountType": "general_investment"
}

Cancel a subscription

Cancels a subscription by its identifier.

Authorizations:
primary-bid-api-secretprimary-bid-api-subscription
path Parameters
subscriptionId
required
string

The identifier of the subscription to cancel

Responses

Response Schema: application/json
status
required
number
required
Array of objects (ValidationErrorModel)
message
required
string

Response samples

Content type
application/json
{
  • "status": 400,
  • "errors": [
    ],
  • "message": "Bad Request"
}

Healthcheck

Get healthcheck status

Retrieve status and availability of the API

Responses

Response Schema: application/json
status
string
object or null
object or null
object
Response Schema: application/json
status
string
object or null
object or null
object

Response samples

Content type
application/json
{
  • "status": "ok",
  • "info": {
    },
  • "error": { },
  • "details": {
    }
}

PrimaryBid

Get in touch with [email protected] to find out more about partnering with PrimaryBid.