JSON feed

Concerned products

✅ Attract ✅ Engage ✅ Convert 🔳 Predict

Introduction

Adway's system relies on indexing JSON feeds on a regular basis, a feed contains a list of all current open jobs in an ATS.

The details of what each individual open job in the feed should contain is described under the data specification section and an example of a JSON feed can be found under the example JSON feed section.

Data exchange

The JSON feed should be made available to Adway through a SSL protected URL (HTTPS).

Security

Adway recommends to protect the JSON feed with authentication , and support the following authentication methods;

Anonymous
Basic authentication
Bearer token (JWT)

Data specification

Below is a technical description of the required and optional data to provide in the JSON feed. The feed should respond with an array of JobPosts, see .

Note that the type JobPost has references to the other types described, such as Location, Contact, Image, Video , Employment and Employer.

JobPost

type JobPost = {
  /** Unique external ats id, typically the id within the ATS for the individual job
   * REQUIRED
  */
  atsJobId: string;

  /** Job title. 
   * REQUIRED
  */
  title: string;

  /** Short descriptive name of the position to fill. 
   * OPTIONAL
  */
  role?: string;

  /** 2 character language codes. 
   * OPTIONAL
   * RECOMMENDED - If not present will be derived from description using language detection which could fail and slow down publishing time
  */
  language?: string;

  /** Full job description (supports HTML). 
   * REQUIRED
  */
  description: string;

  /** A shorter desciprtion of the opportunity. Could be used as is directly in the social media adverts description.
  * OPTIONAL
  */
  shortDescription?: string;

  /** List of category values for the job
   * REQUIRED
   * MINIMUM 1
   */
  categories: string[];

  /** Department the job belongs to
   * OPTIONAL
   */
  department?: string;

  /** Date for when job was published. 
   * OPTIONAL
   * HAS UTC STRING FORMAT (YYYY-MM-DDTHH:mm:ss.sssZ)
   * RECOMMENDED
  */
  publishedDate?: string;

  /** Last date to submit application for job.
   * OPTIONAL
   * HAS UTC STRING FORMAT (YYYY-MM-DDTHH:mm:ss.sssZ)
   * RECOMMENDED
   */
  lastApplicationDate?: string;
  
  /** Link to the job advert on career site. 
   * REQUIRED
  */
  descriptionUrl: string;

  /** Link to the job advert application form on career site. 
   * OPTIONAL
   * RECOMMENDED
  */
  applicationUrl?: string;

  /** List of contact persons for the specific job. 
   * OPTIONAL
   * RECOMMENDED
  */
  contacts?: Contact[];

  /** List of the images related to the job advert
   * OPTIONAL
   * UNIQUE Image.placement - array may contain a maximum of 1 of each Image.placement
  */
  images?: Image[];

  /** List of the videos related to the job advert
   * OPTIONAL
   * UNIQUE Video.placement - array may contain a maximum of 1 of each Video.placement
  */
  videos?: Video[];

  /** List of locations to advertise in. 
   * REQUIRED
   * MINIMUM 1
  */
  locations: Location[];
  
  /** A description of the location to be shown in the advert. 
   * OPTIONAL - If present, will be the displayed location in adverts in place of a text derived from the locations list. Examples: "Remote position in Sweden" or "Sjuhärad".
  */
  locationDescription?: string;

  /** Different attributes of the terms of the employment. 
   * OPTIONAL
  */
  employment?: Employment;

  /** Employer info, for recruitment firms and job boards mostly. 
   * OPTOINAL
  */
  employer?: Employer;

  /** Additional field used for invoicing.
   * OPTIONAL
   */
  costCenter?: string;

  /** Advertising boost package reference
   * OPTIONAL
   */
  boostId?: string;
  
  /** Advertising template reference
   * OPTIONAL
   */
  adTemplateId?: string;
}

Contact

type Contact = {
  /** Name of contact person. 
   * REQUIRED
  */
  name: string;

  /** Contact person email address. 
   * REQUIRED
  */
  email: string;

  /** Contact person phone number. 
   * OPTIONAL
  */
  phone?: string;
  
  /** Contact person professional position or title. 
   * OPTIONAL
  */
  position?: string;
}

Image

type Image = {
  /** Public url pointing to the location of the image. 
   * REQUIRED
   * FILE FORMAT IS ONE OF [".png", ".jpg", ".jpeg"]
  */
  url: string;

  /** Intended placement for the image.
   * REQUIRED
   * IS ONE OF ["feed", "story"]
   * For optimal and guaranteed placments, images provided for 
     feed should have aspect ratio 1:1 and story should have aspect ratio 9:16.
     Other aspect ratios could work, but is not guaranteed due to Social Media platform limitations.
  */
  placement: string;
}

Video

type Video = {
  /** Public url pointing to the location of the video. 
   * REQUIRED
   * FILE FORMAT IS .mp4
  */
  url: string;
  
  /** Public url pointing to the location of the thumbnail image. 
   * REQUIRED
   * FILE FORMAT IS ONE OF [".png", ".jpg", ".jpeg"]
  */
  thumbnail: string;

  /** Intended format for the Video.
   * REQUIRED
   * IS ONE OF ["feed", "story"]
   * For optimal and guaranteed placments, videos provided for 
     feed should have aspect ratio 1:1 and story should have aspect ratio 9:16.
     Other aspect ratios could work, but is not guaranteed due to Social Media platform limitations.
  */
  placement: string;
}

Location

type Location = {
  /** Street address for job advertisment. 
   * OPTIONAL
  */
  street?: string;

  /** ZIP code for job advertisment. 
   * OPTIONAL
  */
  zipCode?: string;

  /** City for the job advertisment. 
   * REQUIRED
  */
  city: string;
  
  /** Municipality for the job advertisment. 
   * OPTIONAL
  */
  municipality?: string;
  
  /** Region or State for the job advertisment. 
   * OPTIONAL
   * RECOMMENDED - improves fallback strategy in case of cities not being viable
  */
  region?: string;

  /** 2 Character ISO standard country code. 
   * REQUIRED
  */
  countryCode: string;

  /** Name of country. 
   * OPTIONAL
  */
  countryName?: string;
}

Employment

type Employment = {
  /** Indication of job being a temporary position. 
   * OPTIONAL
  */
  isTemporary?: boolean;

  /** Indication of job being a part time position. 
   * OPTIONAL
  */
  isPartTime?: boolean;

  /** Indication of job being a fully remote position. 
   * OPTIONAL
  */
  isRemote?: boolean;

  /** Indication of job being a flexibly remote position. 
   * OPTIONAL
  */
  isFlexibleRemote?: boolean;
}

Employer

type Employer = {
  /** Name of the employer company. */
  name: string;

  /** URL to logotype image for the employer company. 
   * OPTIONAL
  */
  logotypeUrl?: string;

  /** Descriptive text about employer company as HTML. 
   * OPTIONAL
  */
  description?: string;
}

Example JSON feed

[
    {
        "atsJobId": "REQ1001",
        "title": "Backend Developer to Nordic Scaleup!",
        "role": "Backend Developer",
        "language": "sv",
        "description": "<p>Do you want to be part of our journey in a fast-growing scale-up, use your knowledge to shape the future of digital talent acquisition, and help us visualize the next step for our products? Then <strong>Adway</strong> might be just the place for you!</p>",
        "shortDescription": "Adway is looking for a new backend developer! Apply now and become part of the purple family! 💜",
        "categories": [
            "Development"
        ],
        "department": "Development",
        "publishedDate": "2022-01-15T11:17:52.207Z",
        "lastApplicationDate": "2022-02-15T11:17:52.207Z",
        "descriptionUrl": "https://adway.ai/jobs/id",
        "applicationUrl": "https://adway.ai/jobs/id/apply",
        "contacts": [
            {
                "name": "John Doe",
                "email": "john.doe@adway.ai",
                "phone": "+46766908070"
            }
        ],
        "images": [
            { 
                "url": "https://adway.ai/jobs/id/square_image.jpg",
                "placement": "feed"
             },
             { 
                "url": "https://adway.ai/jobs/id/portrait_image.jpg",
                "placement": "story"
             }
        ],
        "videos": [
            {
                "url": "https://adway.ai/jobs/id/square_video.mp4",
                "thumbnailUrl": "https://adway.ai/jobs/id/square_image.jpg",
                "placement": "feed"
            },
            {
                "url": "https://adway.ai/jobs/id/portrait_video.mp4",
                "thumbnailUrl": "https://adway.ai/jobs/id/portrait_image.jpg",
                "placement": "story"
            }
        ]
        "locations": [
            {
                "street": "Andra Långgatan 46",
                "zipCode": "41327",
                "city": "Gothenburg",
                "region": "Västra Götaland",
                "countryCode": "SE",
                "countryName": "Sweden"
            }
        ],
        "employment": {
            "isTemporary": false,
            "isPartTime": false,
            "isRemote": true,
            "isFlexibleRemote": true
        },
        "employer": {
            "name": "Adway",
            "logotypeUrl": "https://adway.ai/new/assets/icons/adway-logo--white.svg",
            "description": "<p>Adway was born from the awakening that HR professionals spend too much time marketing to candidates and not enough time meeting them. Ever since it’s our mission to make sure the talent you look for is the talent you speak to.</p>"
        },
        "costCenter": "Tech Department",
        "boostId": null,
        "adTemplateId": null
    },
    {
        "atsJobId": "REQ1002",
        "title": "Frontend Developer to Nordic Scaleup!",
        "language": "sv",
        "description": "<p>Do you want to be part of our journey in a fast-growing scale-up, use your knowledge to shape the future of digital talent acquisition, and help us visualize the next step for our products? Then <strong>Adway</strong> might be just the place for you!</p>",
        "categories": [
            "Development"
        ],
        "publishedDate": "2022-01-15T11:17:52.207Z",
        "lastApplicationDate": "2022-02-15T11:17:52.207Z",
        "descriptionUrl": "https://adway.ai/jobs/id",
        "applicationUrl": "https://adway.ai/jobs/id/apply",
        "locations": [
            {
                "street": "Andra Långgatan 46",
                "zipCode": "41327",
                "city": "Gothenburg",
                "region": "Västra Götaland",
                "countryCode": "SE",
                "countryName": "Sweden"
            }
        ]
    }
]

PreviousGetting started NextJS tag

Last updated 1 year ago