Endpoints

This section aims at presenting all the base endpoints that are part of the SmartRecruiters public Posting API.

Available endpoints:

/postings – method for searching postings

/postings/{postingId} – method for getting details of posting

In an effort to make things consistent, we present each of these methods using the structure below:

  1. Request – GET method to communicate to our API
  2. Path Parameters – all of these are required
  3. Query Parameters – all of these are optional
  4. Response Body
  5. Example http request
  6. Example response

/postings

Description

Lists active postings published by given company.

Request

GET https://api.smartrecruiters.com/v1/companies/{companyIdentifier}/postings?q={query}&limit={limit}&offset={offset}&country={country}&region={region}&city={city}&department={department}&custom_field.{customFieldId}={customFieldValueId}&language={language}

Path Parameters

Name

Type

Description

companyIdentifier

string

The company id as it appears at the end of your default career site. To find have an administrator go to “Settings/Admin” and click on “Career Pages & Job Ads” and it will be what appears after the / in “https://careers.smartrecruiters.com/”

Query Parameters

Name

Type

Description

limit

integer

number of elements to return. max value is 100

offset

integer

number of elements to skip while processing result

country

string

country code filter (part of the location object)

region

string

region filter (part of the location object)

city

string

city filter (part of the location object)

department

string

department filter (department id)

customFieldId

string

customField filter (field id; part of the customField object); works together with customFieldValueId; e.g. custom_field.52d95747e4b0ba7acb9217ea=23aba1d4-4c81-48f7-9ae2-3ab84ee32a80

customFieldValueId

string

customField value (value id; part of the customField object). Multiple value ids can be provided, separated by comma (“,”)

q

string

full-text search query based on a job title, location.

language

string

job ad language; accepts 2-letter ISO 639-1 language code; multiple codes can be provided, separated by comma (“,”)
Exceptions to the language code ISO format:

  • “en-GB” – “English – English (UK)”
  • “fr-CA” – “French – français (Canada)”
  • “pt-BR” – “Portugal – português (Brasil)”
  • “pt-PT” – “Portugal – português (Portugal)”
  • “zh-HK” – “Chinese (Traditional) – 中文 (香港)”
  • “zh-CN” – “Chinese (Simplified) – 中文 (简体)”

Request Body

n/a

Response Body

ListResult containing list of Posting objects. However, some fields might not be set. To get full object use ‘ref’ property.

Example request

curl -i  https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings?offset=10&q=developer

Example response

{
    "limit": 10,
    "offset": 0,
    "totalFound": 2,
    "content": [ 
    {
        "id": "74983486",
        "uuid": "34225731-e7cf-4584-b0b7-78098fe1a66b",
        "name": "test job",
        "jobAdId": "106f35bc-a0e6-4e55-96f9-56835e3f8349",
        "company": {
            "identifier": "smartrecruiters",
            "name": "SmartRecruiters"
        },
        "releasedDate": "2011-12-19T15:28:46.493Z",
        "location": {
             "country": "US", 
             "region": "FL",
             "city": "Orlando",
             "remote": false
             "latitude": "28.557071",
             "longitude": "-81.359463" 
        },  
        "industry": {
            "id": "computer_software",
            "label": "Computer Software"
        },
        "department": {
            "id": 2323,            
            "label": "IT",
            "description": "IT Department"   
        },        
        "function": {
            "id": "engineering",
            "label": "Engineering"
        },
        "typeOfEmployment": {
            "id": "prop_toe_perm",
            "label": "Permanent"
        },
        "experienceLevel": {
            "id": "mid_senior_level",
            "label": "senior"
        },     
        "customField": [
            {
                "fieldId": "52d3c1b32c613b40c5797627",
                "fieldLabel": "Division",
                "valueId": "4b5716a0-9095-4caa-b583-3b03c8ded8c0",
                "valueLabel": "Sales EMEA"
            }
        ],
        "ref": "https://api.smartrecruiters.com/api-v1/companies/smartrecruiters/postings/74983486",
        "creator": {
            "name": "John Doe",
        }
    },
    {
        "id": "74790901",
        "uuid": "45425731-e7cf-4584-a0a7-78098fe1a58a",
        "name": "Account Manager",
        "company": {
            "identifier": "smartrecruiters",
            "name": "SmartRecruiters Inc"
        },
        "releasedDate": "2013-12-19T18:34:21.443Z",
        "location": {
            "city": "San Francisco",
            "region": "CA",
            "country": "us",
            "remote": true
        },
        "industry": {
            "id": "computer_software",
            "label": "Computer Software"       
        },
        "department": {
            "id": 2323,            
            "label": "Finance",
            "description": "Finance Department"
        },
        "function": {
            "id": "engineering",
            "label": "Engineering"
        },
        "typeOfEmployment": {
            "id": "toe_perm",
            "label": "Permanent"
        },
        "experienceLevel": {
            "id": "mid_senior_level",
            "label": "senior"
        },
        "customField": [
            {
                "fieldId": "52d3c1b32c613b40c5797627",
                "fieldLabel": "Division",
                "valueId": "32c87a5d-1365-4dc3-80fe-ecacfb0799c7",
                "valueLabel": "Marketing US"                
            }
        ],
        "ref": "https://api.smartrecruiters.com/api-v1/companies/smartrecruiters/postings/876737562",
        "creator": {
            "name": "John Doe"
        }
    }
]
}

Example requests (executable)

https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings/
https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings/?q=Front%20End
https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings/?offset=2&limit=2
https://api.smartrecruiters.com/v1/companies/smartrecruiters/postings/?city=San%20Francisco

/postings/{postingId}

Description

Content of a job posting with given id.

Note: In order to update content of a job posting available via the Posting API, you need to re-post the job in SmartRecruiters application.

Request

GET https://api.smartrecruiters.com/v1/companies/{companyIdentifier}/postings/{postingId}

Path Parameters

Name

Type

Description

postingId

string

The posting id or uuid from list of postings

companyIdentifier

string

The company id as it appears at the end of your default career site. To find have an administrator go to “Settings/Admin” and click on “Career Pages & Job Ads” and it will be what appears after the / in “https://careers.smartrecruiters.com/”

Query Parameters

n/a

Request Body

n/a

Response Body

Object of PostingDetails type.

Example request

curl -i  https://api.smartrecruiters.com/v1/smartrecruiters/postings/884352026

Example response

{
    "id": "884352026",
    "uuid": "45425731-e7cf-4584-a0a7-78098fe1a58a",
    "name": "SEO Manager",
    "jobId": "a8fe8118-455c-407e-8e84-b9d0201697b8",
    "jobAdId": "106f35bc-a0e6-4e55-96f9-56835e3f8349",
    "company": {
        "name": "SmartRecruiters Inc",
        "identifier": "smartrecruiters"
    },
    "department": {
        "id": 18554,
        "label": "Marketing",
        "description": "Marketing Department"
    }
    "location": {
        "city": "San Francisco",
        "region": "CA",
        "country": "us",
        "remote": true,
        "latitude": "28.557071",
        "longitude": "-81.359463" 
    },
    "industry": {
        "id": "internet",
        "label": "Internet"
    },
    "function": {
        "id": "marketing",
        "label": "Marketing"
    },
    "experienceLevel": {
        "id": "mid_senior_level",
        "label": "Mid-Senior Level"
    },
    customField": [
        {
            "fieldId": "52d95747e4b0ba7acb9217ea",
            "fieldLabel": "Division",
            "valueId": "23aba1d4-4c81-48f7-9ae2-3ab84ee32a80",
            "valueLabel":   "Sales EMEA"
        }
    ],
    "creator": {
        "name": "Jerome Ternynck",
        "avatarUrl": "https://www.smartrecruiters.com/web-api/employees/image/Tz22MEbz"
    },
    "applyUrl": "https://www.smartrecruiters.com/smartrecruiters/74944235-experienced-seo-consultant-?oga=true",
    "jobAd": {
        "sections": {
            "companyDescription": {
                "title": "Company Description",
                "text": "SmartRecruiters is a start-up with a vision [make hiring easy] and a cause [eradicate unemployment]. We have a passion for innovation - especially when it becomes disruptive, and we think the $400bn recruiting industry sucks. So we leverage technology and social media to change the game - and eradicate unemployment along the way.Our free Open SaaS recruiting software takes complexity away from the hiring process, helping businesses gain access to the talent they need, thus creating and filling more jobs faster. Over 57,000 customers have already signed up.
            },
            "jobDescription": {
                "title": "Job Description",
                "text": "SmartRecruiters is seeking an SEO Manager with B2B experience . We want someone that can take their knowledge of SEO and data analytics to dramatically improve our organic search results. This individual will define and execute the organic search efforts at SmartRecruiters and will be responsible to define the SEO Strategy & tools needed to make and implement the SEO recommendations. We are looking for a SEO professional, with excellent problem solving skills that has a fundamental understanding of SEO issues involving site architecture, keyword generation, search-friendly content, link building strategies, blog optimization, and metrics-driven SEO . Experience in the recruiting industry is a plus but not essential.
                Responsibilities:
                Build insights about our SEO efforts
                Inform & define our SEO strategy to optimize for growth, engagement, and revenue
                Direct experience with SEO for dynamic, JavaScript web applications
                Work closely with Marketing, Engineering, and Data teams to build scalable marketing tools that maintain our SEO efforts
                Build a SEO dashboard to track success of SEO efforts including organic sign- ups and conversions
                Invent, design, implement and scale ROI-positive SEO campaigns
                Work with Social Media to optimize the use of social assets and strategies as they pertain to SEO
                Ensure SmartRecruriters has a strong online presence which results in user signups.
            },
            "qualifications": {
                "title": "Qualifications",
                "text": "
                3 - 5  years total experience doing SEO/Internet Marketing
                Great communicator - must be proactive
                Experience dealing with SEO with Yahoo/Bing/Google
                Detailed knowledge of Google Analytics, Google Webmaster tools, and other SEO tools and their use to direct SEO analysis
                Great organization skills and attention to detail
            },
            "additionalInformation": {
                "title": "Additional Information",
                "text": "
                SmartRecruiters is a well-funded start-up with a great team. You’ll enjoy our open culture and key values [work smart, have fun, make the difference], as well as cool offices South of Market in San Francisco and in NORI [North of River], Krakow.
                Besides a great work environment and the opportunity to change the world, we offer competitive salary and benefits as well as stock options. So, don't be shy, click Apply below and come by for coffee.
            }
        }
    },
    "active": true
}

Did this page help you?