Position API

The Position API allows you to search for positions with their contact information, managers and direct reports using a variety of filters. It’s powerful to enrich exsisting org chart strucutres or lists of leads.

Find Positions


POST https://api.theorg.com/v1/positions

Parameter	Value
Url	https://api.theorg.com/v1/positions
Method	`POST`
Body	Request body
Cost	One credit pr. returned row
Result sorting	Most relevant first

Request body

Parameter	Type	Description	Required
`limit`	integer	The maximum number of results to return (max: 1000)	`true`
`offset`	integer	The offset of the results (max: 10,000)	`true`
`filters`	object		`true`
`filters.personIds`	array	Internal person IDs to search for	`false`
`filters.companyDomains`	array	Company domains to search for	`false`
`filters.companyLegalStatuses`	array of LegalStatus	Legal statuses of companies	`false`
`filters.industries`	array of Industry	Industries to search for	`false`
`filters.locations`	array	Location filters with country and state	`false`
`filters.locations.country`	string	Two-letter country code (ISO 3166-1 alpha-2)	`true`
`filters.locations.state`	string	Either two letter code or plain text	`false`
`filters.employeeRanges`	array of EmployeeRange	Company size ranges	`false`
`filters.orgChartLevels`	array	Org chart levels to search for	`false`
`filters.departments`	array of Department	Departments to search for	`false`
`filters.latestFundingStages`	array of FundingStage	Latest funding stages	`false`
`filters.jobTitles`	array	Job titles and keywords	`false`
`filters.previousCompanyDomains`	array	Previous company domains	`false`
`filters.personFullNames`	array	Full names or parts of names	`false`
`filters.hiredWithinDays`	integer	Days since hire	`false`
`filters.verifiedWorkEmail`	boolean	Whether person has verified work email	`false`

Example

Return rich information including contacts on the top marketing people at Apple:

Requesting marketing people at Apple


curl --location 'https://api.theorg.com/v1/positions' \
--header 'X-Api-Key: **********************a02e' \
--header 'Content-Type: application/json' \
--data '{
    "limit": 1,
    "offset": 0,
    "filters": {
        "companyDomains": ["apple.com"],
        "departments": ["marketing"]
    }
}'

Show response


{
    "data": {
        "items": [
            {
                "id": 179671,
                "slug": "bob-borchers",
                "name": "Bob Borchers",
                "title": "VP, WW Product Marketing",
                "bio": "Bob Borchers returned to Apple after working at Google and [Dolby Laboratories](/org/dolby-laboratories). Borchers was previously at Apple for four years in the early 2000s. From August 2004 he was a director of product marketing for the iPod ecosystem. He was promoted to senior director of marketing on the iPhone in 2005. He left Apple in June 2009. In his new role, he will oversee iOS and iCloud, as well as privacy marketing issues.",
                "url": "https://theorg.com/org/apple/org-chart/bob-borchers",
                "functions": [
                    "marketing",
                    "product"
                ],
                "workEmail": null,
                "directDial": null,
                "profilePhotoUrl": "https://cdb.theorg.com/620258b6-a8d1-4c4a-b932-c8878769d2e9.jpg",
                "linkedInUrl": "https://www.linkedin.com/in/bborchers",
                "twitterUrl": null,
                "facebookUrl": null,
                "startDate": null,
                "currentCompany": {
                    "id": "5a8fbc82-c357-11e7-abc4-cec278b6b50a",
                    "slug": "apple",
                    "logoUrl": "http://localhost:1234/1243da72-2ea0-4425-bc87-febd505d1528.jpg",
                    "name": "Apple",
                    "legalStatus": "company",
                    "domains": [
                        "apple.com"
                    ],
                    "industries": [
                        "electronics",
                        "manufacturing",
                        "computer_hardware"
                    ],
                    "employeeRange": ">10000",
                    "linkedInUrl": "https://linkedin.com/company/162479/",
                    "websiteUrl": "https://www.apple.com/",
                    "url": "https://testing.theorg.com/org/apple",
                    "embedUrl": "https://testing.theorg.com/org/apple/embed"
                },
                "previousCompanies": [],
                "managerIds": [
                    271
                ],
                "reportIds": [],
                "location":     {
                    "country": "US",
                    "state": "NY",
                    "city": "Cupertino",
                    "latitude": 37.3230,
                    "longitude" 122.0322
                }
            }            
        ],
        "totalCreditsUsed": 1,
        "totalResults": 131
    }
}

Credit Check Utility

The position finding endpoint will deduct one credit pr. row returned. Due to this it can be handy to understand the potential credit cost associated with a specific position finding request.


POST https://api.theorg.com/positions/credit-usage

Parameter	Value
Url	https://api.theorg.com/v1/positions/credit-usage
Method	`POST`
Body	Request body
Cost	Free

Example

Same example as the above - we want to see how many it will cost to return contact infomation and relational data of all marketing people at Apple.

Requesting marketing people at Apple


curl --location 'https://api.theorg.com/v1/positions/credit-usage' \
--header 'X-Api-Key: **********************a02e' \
--header 'Content-Type: application/json' \
--data '{
    "limit": 1000,
    "offset": 0,
    "filters": {
        "companyDomains": ["apple.com"],
        "departments": ["marketing"]
    }
}'

Show response


{
    "data": {
        "creditCost": 131,
        "remainingCredits": 100
    }
}

💡

A specific row can be returned mulitple times at no additional cost within 24 hours of the intitial return.