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

NameTypeDescription
companyIdentifierstringThe 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

You can find the full list of available query parameters under the API Reference tab.

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",
        "defaultJobAd": true,
        "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

NameTypeDescription
postingIdstringThe posting id or uuid from list of postings
companyIdentifierstringThe 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",
    "defaultJobAd": true,
    "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
}