PrimaryBid Commercial API (2.0)
Download OpenAPI specification:Download
PrimaryBid Commercial Integrations API
Get all offers
Retrieves all accessible PrimaryBid offers.
Authorizations:
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:
|
offset | number Example: offset=20 When specified, it refers to the maximum number of offers that should be returned in a single API response. |
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. |
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
- 200
- 400
[- {
- "id": "string",
- "offerType": "ipo",
- "offerSubType": "company_placing",
- "details": {
- "countryCode": "GB",
- "estTargetRaise": 0,
- "minTargetRaiseCombined": 0,
- "status": "open_for_subscription",
- "type": "ipo",
- "subType": "primary",
- "pressReleaseLink": "string",
- "membershipRequired": "Optional",
- "offeringDocuments": {
- "title": "string",
- "documentUrl": "string"
}
}, - "textProperties": {
- "legalDisclaimer": "string",
- "specialInstruction": "string",
- "restriction": "string",
- "offerDiscount": "string",
- "priceless": "string",
- "useOfProceeds": "string",
- "title": "string",
- "companyAnnouncements": "string",
- "keyInformation": "string"
}, - "pricingAndOrderLimits": {
- "priceType": "fixed",
- "offerPrice": 0,
- "minimumPrice": 0,
- "maximumPrice": 0,
- "discountFrom": 0,
- "discountTo": 0,
- "discount": 0,
- "currency": "GBX",
- "hardMaxLimit": 0,
- "hardMinLimit": 0,
- "acceptedCurrency": "GBP"
}, - "dates": {
- "offerStartDateTime": "2019-08-24T14:15:22Z",
- "offerEndDateTime": "2019-08-24T14:15:22Z",
- "offerEarlyClose": "2019-08-24T14:15:22Z",
- "lastModifiedOn": "2019-08-24T14:15:22Z",
- "admissionDateTime": "2019-08-24T14:15:22Z"
}, - "issuer": {
- "id": "string",
- "companyName": "string",
- "businessDescriptionText": "string",
- "sector": "string",
- "ticker": "string",
- "exchangeMic": "string",
- "sellerName": "string",
- "fttRequired": true,
- "securityIdentifier": "string"
}
}
]
Get an offer by its identifier
Authorizations:
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
- 200
- 400
{- "id": "string",
- "offerType": "ipo",
- "offerSubType": "company_placing",
- "details": {
- "countryCode": "GB",
- "estTargetRaise": 0,
- "minTargetRaiseCombined": 0,
- "status": "open_for_subscription",
- "type": "ipo",
- "subType": "primary",
- "pressReleaseLink": "string",
- "membershipRequired": "Optional",
- "offeringDocuments": {
- "title": "string",
- "documentUrl": "string"
}
}, - "textProperties": {
- "legalDisclaimer": "string",
- "specialInstruction": "string",
- "restriction": "string",
- "offerDiscount": "string",
- "priceless": "string",
- "useOfProceeds": "string",
- "title": "string",
- "companyAnnouncements": "string",
- "keyInformation": "string"
}, - "pricingAndOrderLimits": {
- "priceType": "fixed",
- "offerPrice": 0,
- "minimumPrice": 0,
- "maximumPrice": 0,
- "discountFrom": 0,
- "discountTo": 0,
- "discount": 0,
- "currency": "GBX",
- "hardMaxLimit": 0,
- "hardMinLimit": 0,
- "acceptedCurrency": "GBP"
}, - "dates": {
- "offerStartDateTime": "2019-08-24T14:15:22Z",
- "offerEndDateTime": "2019-08-24T14:15:22Z",
- "offerEarlyClose": "2019-08-24T14:15:22Z",
- "lastModifiedOn": "2019-08-24T14:15:22Z",
- "admissionDateTime": "2019-08-24T14:15:22Z"
}, - "issuer": {
- "id": "string",
- "companyName": "string",
- "businessDescriptionText": "string",
- "sector": "string",
- "ticker": "string",
- "exchangeMic": "string",
- "sellerName": "string",
- "fttRequired": true,
- "securityIdentifier": "string"
}
}
Get all allocations
Retrieves all accessible PrimaryBid allocations.
Authorizations:
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
- 200
- 400
[- {
- "offerId": "string",
- "price": 0,
- "priceCurrency": "GBX",
- "allocationCount": 0,
- "allocations": [
- {
- "subscriptionId": "string",
- "clientSubscriptionReference": "string",
- "investorReferenceType": "nino",
- "investorReference": "string",
- "receivedByPrimaryBidTimestamp": "2019-08-24T14:15:22Z",
- "amountRequested": 0,
- "currency": "GBX",
- "amountAccepted": 0,
- "amountAllocated": 0,
- "sharesAllocated": 0,
- "message": "string",
- "clientSubscriptionTimestamp": "2019-08-24T14:15:22Z",
- "accepted": true,
- "membershipCode": "string",
- "accountType": "general_investment",
- "status": "unallocated",
- "membershipStatus": "verified",
- "subscriptionCategory": "retail"
}
]
}
]
Get allocations for offer
Gets all allocations by associated offerId mapped to OfferAllocationModel.
Authorizations:
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. |
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
- 200
- 400
{- "offerId": "string",
- "price": 0,
- "priceCurrency": "GBX",
- "allocationCount": 0,
- "allocations": [
- {
- "subscriptionId": "string",
- "clientSubscriptionReference": "string",
- "investorReferenceType": "nino",
- "investorReference": "string",
- "receivedByPrimaryBidTimestamp": "2019-08-24T14:15:22Z",
- "amountRequested": 0,
- "currency": "GBX",
- "amountAccepted": 0,
- "amountAllocated": 0,
- "sharesAllocated": 0,
- "message": "string",
- "clientSubscriptionTimestamp": "2019-08-24T14:15:22Z",
- "accepted": true,
- "membershipCode": "string",
- "accountType": "general_investment",
- "status": "unallocated",
- "membershipStatus": "verified",
- "subscriptionCategory": "retail"
}
]
}
Get all subscriptions
Retrieves all accessible PrimaryBid subscriptions.
Authorizations:
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. |
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
- 200
[- {
- "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"
}
]
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:
Request Body schema: application/jsonrequired
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
- Payload
{- "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
- 201
- 400
{- "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:
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
- 200
{- "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:
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
- 400
{- "status": 400,
- "errors": [
- {
- "property": "string",
- "messages": [
- "string"
]
}
], - "message": "Bad Request"
}
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
- 200
- 503
{- "status": "ok",
- "info": {
- "database": {
- "status": "up"
}
}, - "error": { },
- "details": {
- "database": {
- "status": "up"
}
}
}