Zenploy API v1
Introduction
Authentication
Errors
Objects
Company
Location
Department
Job
Resource
Endpoints
Company
Location
Department
Job
Resource
Introduction

The Zenploy API allows third-parties to integrate with Zenploy by accessing customer data. This is especially useful if you want to build your own career page or already have one and want to integrate your jobs into it, by using this API you can make it automatically adjust whenever a change is made in Zenploy.

Our API follows the REST pattern and uses the JSON data format.

All paths in the documentation are relative to the base API url.

                    https://api.zenploy.io/v1
                

All API endpoints return one object or a list of objects upon success and the returned objects are wrapped in JSON in different ways depending on whether it is a list or not.

                    {
  "object": {
    "id": "wsakXxWcQal3naor",
    ...
  }
}

                
                    {
  "count": 2,
  "objects": [{
    "id": "IJ5rNNdu8QwRnfDQ",
    ...
  }, {
    "id": "MCFX35ePlLg5HWEM",
    ...
  }]
}

                
Authentication

There is no authentication required at the moment, all endpoints are read-only and public.

Errors

Whenever something goes wrong the API returns an appropriate HTTP status code (4xx or 5xx) along with an error message in the response body. All errors messages are formatted the same way and there is a defined list of error codes that we support.

                    {
  "error": {
    "code": code,
    "message": message
  }
}
                
Code HTTP status Description
bad_request 400

Your request was not formatted correctly. Bad parameter, missing parameter, wrong data format, etc...

forbidden 403

The requested resource is not accessible to you.

not_found 404

The requested resource is not available or does not exist.

method_not_allowed 405

The HTTP method used isn't supported for this endpoint.

server_error 500

Something unexpectedly went wrong on our side.

Objects
Company

This object represents a company and contains descriptive information about it such as its name or the number of employees.

id String

Unique identifier for the company.

name String

Name of the company.

num_employees Range

A range for the number of employees at the company.

summary String

A summary of what the company does.

industry String

Name of the associated industry.

logo Resource

Company logo resource.

website String

URL for the company website.

social Object

Social media profile URLs, the possible keys are: linkedin, facebook and twitter.

Example

                            {
  "id":"LP6kqmsorq1RbN2Q",
  "name": "Zenploy",
  "summary": "This is the summary of our awesome company.",
  "industry": "Software",
  "website": "https://www.zenploy.io",
  "social": {
    "twitter": null,
    "linkedin": null,
    "facebook": "https://www.facebook.com/zenploy"
  },
  "num_employees": {
    "min": 1,
    "max": 5
  },
  "logo": {
    "id": "v7Uh5XbHxE98NNDJ",
    "type": "image",
    "public": true,
    "preview": {
      "ready": false,
      "available": false
    },
    "file": {
      "size": 5696,
      "name": "logo.png"
    },
    "download_url": "https://www.zenploy.io/data/v7Uh5XbHxE98NNDJ"
  }
}
                        
Location

This object represents a physical location.

id String

Unique identifier for the location.

name String

Name or label given to this location.

address Object

Associated postal address.

street String

Street address.

city String

City name.

zip_code String

Zip code.

state String

State or region name (if applicable).

country String

Country name.

Example

                            {
  "id":"TTki4l7ljOco6L0H",
  "name": "San Francisco Office",
  "address": {
    "street": "123 main st.",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94101",
    "country": "United States"
  }
}
                        
Department

This object represents a department within a company, such as "Engineering" or "Accounting".

id String

Unique identifier for the department.

name String

Name or label given to this department.

Example

                            {
  "id": "p2ehitprbQe43pnX",
  "name": "Engineering"
}
                        
Job

This object represents a job offer, it contains its description and attributes.

id String

Unique identifier for the job.

title String

Job title.

updated_at Integer

UNIX timestamp of the last update.

description String

HTML-formatted job description.

description_text String

Text-only job description.

profile String

HTML-formatted profile for this job.

profile_text String

Text-only profile for this job.

apply_url String

URL of the application form for this job, use it to collect candidate applications. e.g. https://jobs.zenploy.io/amce/2xSW8zMKD95asFnG/apply

location Location

Where the job is located.

department Department

Associated company department.

attributes Object

Optional attributes of the job.

level Range

Range of experience required, values can be one of: entry, junior, middle, senior or expert.

type String

Type of contract that's offered, can be one of: fulltime, parttime, contract, internship, apprenticeship or interim.

education String

Range of level of education required, values can be one of: highschool, undergraduate, graduate or postgraduate.

telecommute String

Describes the telecommute policy, can be one of: yes, no or possible.

salary Range

Salary range offered.

equity Range

Equity range offered, if any, expressed in percents.

duration Range

Range of possible duration if it's a temporary position.

start_date String

Description of when the job should start, e.g. Early June 2019 or ASAP.

Example

                            {
  "id": "2jEdje53xAEzUK5t",
  "title": "Senior Software Engineer",
  "updated_at": 1559854197,
  "description": "We're an awesome company, come be part of it!!",
  "description_text": "We're an awesome company, come be part of it!!",
  "profile": "We're looking for someone great.",
  "profile_text": "We're looking for someone great.",
  "apply_url": "https://jobs.zenploy.io/amce/5ZJFy9FvhGJAZPPO/apply",
  "location": {
    "id":"TTki4l7ljOco6L0H",
    "name": "SF Office",
    "address": {
      "street": "123 main st.",
      "city": "San Francisco",
      "state": "CA",
      "zip_code": "94101",
      "country": "United States"
    }
  },
  "department": {
    "id": "m7P0oaXl8FShlqat"
    "name": "Engineering",
  },
  "attributes": {
    "type": "fulltime",
    "level": {
      "min": "middle",
      "max": "senior"
    },
    "education": {
      "min": "graduate",
      "max": null
    },
    "duration": null
    "telecommute": "no",
    "start_date": "2020-01-01",
    "salary":{
      "min": 5000,
      "max": 10000,
      "period": "monthly",
      "currency": "$"
    },
    "equity": {
      "min": 1,
      "max": 2
    }
  }
}
                        
Resource

This represents a file resource such as an image or a PDF document.

id String

Unique identifier for the resource.

type String

Data type associated with this resource, can be one of:
pdf, ms_doc, image, text, url or other.

public Boolean

Whether this resource is public or protected behind authentication.

file Object

Atributes of the associated file.

name String

File name.

size Integer

Size in bytes.

preview Object

Information about the preview thumbnail.

available Boolean

Whether this resource can be previewed.

ready Boolean

Whether the preview thumbnail is done being generated.

url String

URL to retrive the preview thumbnail for this resource (if available and ready).

download Object

Download information.

available Boolean

Whether this resource can be downloaded.

url String

URL to download the raw resource data (if available).

Example

                            {
  "id": "v7Uh5XbHxE98NNDJ",
  "type": "image",
  "public": true,
  "preview": {
    "ready": false,
    "available": false
  },
  "file": {
    "size": 5696,
    "name": "logo.png"
  },
  "download_url": "https://www.zenploy.io/data/v7Uh5XbHxE98NNDJ"
}
                        
Endpoints
Company
GET /company/:company_name
URL parameters
company_name

The name of the company you want to retrieve information about.

Query parameters
This endpoint does not take any query parameter.
Response
200 OK with a response body containing a Company object.
Location
GET /company/:company_name/locations
URL parameters
company_name

The name of the company you want to retrieve information about.

Query parameters
This endpoint does not take any query parameter.
Response
200 OK with a response body containing a list of Location objects.
GET /company/:company_name/location/:location_id
URL parameters
company_name

The name of the company you want to retrieve information about.

location_id

The id of the location to retrieve.

Query parameters
This endpoint does not take any query parameter.
Response
200 OK with a response body containing a Location object.
Department
GET /company/:company_name/departments
URL parameters
company_name

The name of the company you want to retrieve information about.

Query parameters
This endpoint does not take any query parameter.
Response
200 OK with a response body containing a list of Department objects.
GET /company/:company_name/department/:department_id
URL parameters
company_name

The name of the company you want to retrieve information about.

department_id

The id of the department to retrieve.

Query parameters
This endpoint does not take any query parameter.
Response
200 OK with a response body containing a Department object.
Job
GET /company/:company_name/jobs
URL parameters
company_name

The name of the company you want to retrieve information about.

Query parameters
filters[location]

Id of the location to filter by.

filters[department]

Id of the department to filter by.

filters[level]

Experience level to filter by, can be one of:
entry, junior, middle, senior or expert.

filters[type]

Employment type to filter by, can be one of:
fulltime, parttime, contract, internship, apprenticeship or interim.

filters[education]

Education requirement to filter by, can be one of:
highschool, undergraduate, graduate or postgraduate.

filters[telecommute]

Telecommute preference to filter by, can one of:
yes, no or possible.

Response
200 OK with a response body containing a Job object.
Example
                                      curl -X GET "https://api.zenploy.io/v1/company/myCompanyName/jobs?filters[location]=ngZJgsXME2nUGENK&filters[level]=junior&filters[telecommute]=yes"
                                  
GET /company/:company_name/job/:job_id
URL parameters
company_name

The name of the company you want to retrieve information about.

job_id

The id of the job to retrieve.

Query parameters
This endpoint does not take any query parameter.
Response
200 OK with a response body containing a list of Job objects.
Resource
GET /resource/:resource_id
URL parameters
resource_id

The id of the resource to retrieve.

Query parameters
This endpoint does not take any query parameter.
Response
200 OK with a response body containing a Resource object.
Send us a message
Give us feeback or report an issue.
Visit our support page too.