Skip to main content

[POST] - Create Subscription

  • Updated

This API allows you to create subscriptions for Company, FamilyTree, People and News. Use this API to receive notification for each change to the subscribed company, people and related news items.

Endpoint

POST https://api.insideview.com/api/v1/subscription

Request

HTTP Headers

Header Name Type Required Description
accessToken String Yes Valid access token.
See Authentication and Authorization Overview for more details.
Accept String No Selects the response's content type.  
Valid values are application/json and application/xml (default). 

Form Parameters

Parameter Name Type Required Description
subscriptionType String Yes Valid values are "company" or "companyNews" or "people" or "companyFamilyTree"
name String No Name of the subscription
description String No  Description of the subscription
frequency String Yes

Frequency at which you want to be notified.  The frequency can be expressed in (exclusively): month (d), weeks (w), days (d), hours (h) or minutes (M)
Ex.: 7d = seven days, 3w = 3 weeks
Note: for subscriptions of type company and people, the minimal frequency is 1 day.  For subscriptions of type companyNews, the minimal frequency is 15 minutes.

For subscription of Type "companyFamilyTree" the minimum frequency is 1w.
startTime String Yes Date and time of the first notification.  Subsequent notifications will be triggered based on the frequency.
String in ISO 8601 format, e.g., "2015-02-01T00:00:00-08:00"
companyIds String Yes*

*If Subscription type is "company" or "companyNews" or "companyFamilyTree", this field is mandatory.

For "companyFamilyTree" only Ultimate Parent Company IDs are supported.

Comma-separated list of company IDs to subscribe to
Maximum list size: 5,000 IDs
peopleIds String Yes* * If Subscription type is "people" this field is mandatory. Comma-separated list of people IDs to subscribe to Maximum list size: 5,000 IDs
fields String No

Comma-separated list of fields. 

Add the fields you are interested in and for which a notification should be triggered in case of value change.

subscriptionType = "company"
Valid values: 

all(default), Name, ActiveStatus, Revenue, Address, CompanyStatus, CompanyType, FinancialYearEnd, Employees, EmployeeRange, Fax, Naics, Sic, PrimaryIndsutry, Phone, RevenueRange, Ticker, Websites, companyStatusV2, companyTypeV2, siteTypes, businessStructure, siteCount, siteLocationCount

 

subscriptionType = "people"

Valid values:

all (Default), active, name, facebookHandle, linkedInHandle, twitterHandle, education, titles, phone, email, salary, description, imageUrl, age, newEmployment, executiveMobileNo 
agents  String  No Comma-separated list of news agents.
Add the agents you are interested in and for which a notification should be triggered in case of matching company news.
Valid values: ALL (Default), LEADERSHIP_CHANGES, NEW_OFFERINGS, PARTNERSHIPS, COMPANY_PRESENTATION, LITIGATION, COMPLIANCE, RESEARCH_DEVELOPMENT, DATA_SECURITY, FUNDING_DEVELOPMENTS, BANKRUPTCY_RESTRUCTURING, REALESTATE_DEALS, REALESTATE_CONSTRUCTION, CORPORATE_CHALLENGES, ACQUISITIONS, EXPANDING_OPERATIONS, COST_CUTTING, OUTPERFORMING, UNDERPERFORMING
webhook String No Webhook URL. For example: https://my.domain.com/ivwebhook
cron String No Cron expression for custom frequency settings
See the Quartz Documentation for the syntax details.
Ex.: 0 0 12 * * ? ( For generating alerts at 12 PM everyday).
signingSecret String No Key to be used for SHA1 encoding of the content in the custom header X-InsideViewAPI-AlertDataSignature (see configuring Webhook for more details).

Responses

HTTP 200

Returns either a JSON or XML data structure depending on the request Accept header. 

Type: application/json+company

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "/",
  "type": "object",
  "properties": {
    "subscriptionId": {
      "id": "subscriptionId",
      "type": "string"
    },
    "subscriptionType": {
      "id": "subscriptionType",
      "type": "string"
    }
  }
}

Example

{
  "subscriptionId": "vglucce04iseep189haa",
  "subscriptionType": "company"
}

Type: application/json+companyfamilytree

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "/",
  "type": "object",
  "properties": {
    "subscriptionId": {
      "id": "subscriptionId",
      "type": "string"
    },
    "subscriptionType": {
      "id": "subscriptionType",
      "type": "string"
    }
  }
}

Example

{
  "subscriptionId": "vglucce04iseep189hbc",
  "subscriptionType": "companyfamilytree"
}

Type: application/json+company

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "/",
  "type": "object",
  "properties": {
    "subscriptionId": {
      "id": "subscriptionId",
      "type": "string"
    },
    "subscriptionType": {
      "id": "subscriptionType",
      "type": "string"
    }
  }
}

Example

{
  "subscriptionId": "vglucce04iseep189haa",
  "subscriptionType": "company"
}

Type: application/json+companyfamilytree

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "/",
  "type": "object",
  "properties": {
    "subscriptionId": {
      "id": "subscriptionId",
      "type": "string"
    },
    "subscriptionType": {
      "id": "subscriptionType",
      "type": "string"
    }
  }
}

Example

{
  "subscriptionId": "vglucce04iseep189hbc",
  "subscriptionType": "companyfamilytree"
}

Type: application/json+companyNews

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "/",
  "type": "object",
  "properties": {
    "subscriptionId": {
      "id": "subscriptionId",
      "type": "string"
    },
    "subscriptionType": {
      "id": "subscriptionType",
      "type": "string"
    }
  }
}

Example

{
  "subscriptionId": "vglucce04iseep189haa",
  "subscriptionType": "companynews"
}

Type: application/json+people

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "/",
  "type": "object",
  "properties": {
    "subscriptionId": {
      "id": "subscriptionId",
      "type": "string"
    },
    "subscriptionType": {
      "id": "subscriptionType",
      "type": "string"
    }
  }
}

Example

{
  "subscriptionId": "vglucce04iseep189haa",
  "subscriptionType": "people"
}

Type: application/xml+company

Schema

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">

    <xs:element name="subscription" type="CreateSubscriptionDTO"/>

    <xs:complexType name="CreateSubscriptionDTO">
        <xs:sequence>
            <xs:element name="subscriptionId" type="xs:string" />
            <xs:element name="subscriptionType" type="xs:string" />
	    </xs:sequence>
    </xs:complexType>
</xs:schema>

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<subscription>
    <subscriptionId>q8occ24uen80qqt2dde1</subscriptionId>
    <subscriptionType>company</subscriptionType>
</subscription>

Type: application/xml+companyfamilytree

Schema

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">

    <xs:element name="subscription" type="CreateSubscriptionDTO"/>

    <xs:complexType name="CreateSubscriptionDTO">
        <xs:sequence>
            <xs:element name="subscriptionId" type="xs:string" />
            <xs:element name="subscriptionType" type="xs:string" />
	    </xs:sequence>
    </xs:complexType>
</xs:schema>

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<subscription>
    <subscriptionId>vglucce04iseep189hbc</subscriptionId>
    <subscriptionType>companyfamilytree</subscriptionType>
</subscription>

Type: application/xml+companyNews

Schema

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">

    <xs:element name="subscription" type="CreateSubscriptionDTO"/>

    <xs:complexType name="CreateSubscriptionDTO">
        <xs:sequence>
            <xs:element name="subscriptionId" type="xs:string" />
            <xs:element name="subscriptionType" type="xs:string" />
	    </xs:sequence>
    </xs:complexType>
</xs:schema>

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<subscription>
    <subscriptionId>q8occ24uen80qqt2dde1</subscriptionId>
    <subscriptionType>companynews</subscriptionType>
</subscription>

Type: application/xml+people

Schema

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">

    <xs:element name="subscription" type="CreateSubscriptionDTO"/>

    <xs:complexType name="CreateSubscriptionDTO">
        <xs:sequence>
            <xs:element name="subscriptionId" type="xs:string" />
            <xs:element name="subscriptionType" type="xs:string" />
	    </xs:sequence>
    </xs:complexType>
</xs:schema>

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<subscription>
    <subscriptionId>q8occ24uen80qqt2dde1</subscriptionId>
    <subscriptionType>people</subscriptionType>
</subscription>

HTTP Error Codes

If the start date is less than the current date

{
       "errorType": "VALIDATION_ERROR",
       "status": 400,
        "message": "Invalid start time, it must be greater than the current time",
        "diagnosticCode": "fltln8qr0ta3h7vul3ng",
        "errorNumber": "400-1504"
}

If a frequency is not provided

{
        "errorType": "VALIDATION_ERROR",
         "status": 400,
         "message": "Invalid frequency",
         "diagnosticCode": "l7b8alnku4iqfnrqugk",
         "errorNumber": "400-1503"
}

If  a subscription type is not provided

{
         "errorType": "VALIDATION_ERROR",
         "status": 400,
         "message": "Invalid Subscription type.",
         "diagnosticCode": "dnaat1r17gut7ppq4rcj",
         "errorNumber": "400-1508"
}

If CompanyId is not provided

{
         "errorType": "VALIDATION_ERROR",
         "status": 400,
         "message": "Invalid Company ID",
         "diagnosticCode": "2iof9vopm38ddsm9eivo",
         "errorNumber": "400-1501"
}
 
 

Was this article helpful?

0 out of 0 found this helpful