How to get a personal API key

Get in touch with our support team via in-app chat or send an email to sales@jobjet.com to request your API key. We’ll be happy to grant you access just as soon as you need it. 

Authentification

The Jobjet API supports simple, API-key driven authentication that doesn't require a complex series of authentication steps. 

The caller should supply every API call with an api_key parameter that passes the valid API key associated with his or her account. 

For example:

POST https://api.jobjet.com/profiles/enrich?api_key=f53bf423-ead8-4d02-8a8b-1baa59386a77

HTTP Headers

The Jobjet API tracks credit usage and other limits through custom HTTP headers that are returned as a part of the response. No matter what API call is coming to the server, the API always returns all applicable limits in the custom HTTP headers.

The Jobjet API supports the following HTTP headers:

  • x-credits-remain - The amount of remaining credits available for contact information purchase.
  • x-allowed-calls - The number of remaining API calls per given interval. By default, it is set to 30 calls per 60 seconds.
  • x-allowed-calls-interval - The interval, in seconds, that limits throughput of API calls. Typically a minute (60 seconds).
  • x-allowed-batch-size - The maximum allowed batch size for POST request.
  • x-search-id - The unique identification of the run search, mostly required for asynchronous POST requests. If provided in request, the API returns it, so the caller can track run searches on its side.

People API

The Jobjet API allows two modes of candidate enrichment: synchronous and asynchronous.

Both methods have the same authentication and request/response headers. Both methods store a candidate in your Jobjet account, run the enrichment process, update the candidate in Jobjet and return it back.

For successful enrichment, there are three minimal combinations of contact data required for a successful return. Jobjet needs at least one of these data combinations to work properly.

  • First name + last name + email
  • First name + last name + phone
  • First name + last name + Social URL (Github, AngelList, LinkedIn, Facebook)

Our existing process does not allow us to run the enrichment process if the above data is not present. You will get a “422 Unprocessable Entity” in the case of a request that lacks the required data.

Request and response format is very similar in both cases and consists of the candidate profile in our format:

{
    "salutation":"Mr|Mrs|Ms|Dr|<other>",
    "firstName":"Jack",
    "middleName":"Jr",
    "lastName":"Daniels",
    "suffix":"MD|<other>",
    "nickname":"whiskey",
    "location":"Santa Monica, CA",
    "summary":"Resume summary",
    "companyName":"Jobjet, inc",
    "currentTitle":"Data Scientist",
    "industry":"",
    "skills":[
        "Statistics",
        "Python"
    ],
    "emails":[
        {
            "email":"jack@daniels.com",
            "deliveryType":"catchall",
            "type":"home|work|<other>"
        }
    ],
    "addresses":[
        {
            "addressLine1":"123 Crown Point Drive",
            "addressLine2":"Suite 124",
            "addressLine3":"",
            "addressLine4":"",
            "city":"San Diego",
            "country":"US",
            "county":"",
            "postalCode":"90001",
            "state":"CA",
            "type":"home|work|<other>"
        }
    ],
    "phones":[
        {
            "code":"777",
            "number":"555 5555",
            "lineType":"voip",
            "type":"home|work|<other>"
        }
    ],
    "websites":[
        {
            "website":"https://jobjet.com"
        }
    ],
    "socialProfiles":[
        {
            "profile":"https://www.linkedin.com/in/jackdanielsd"
        }
    ],
    "workHistory":[
        {
            "title":"Data Scientist",
            "summary":"",
            "companyName":"Jobjet",
            "companyUrl":"https://jobjet.com/",
            "location":"Santa Monica, CA",
            "startDate":"2014-01-01T00:00:00",
            "endDate":""
        }
    ],
    "education":[
        {
            "school":"University of Canberra",
            "summary":"",
            "degree":"",
            "major":"Advertising, Marketing Communications",
            "startDate":"",
            "endDate":""
        }
    ]
}

None of the fields are required, but the existing enrichment process can only work with the use of the minimal combinations specified above.

  • If emails key is specified, it should be an array of objects. In the email object only email key is required.
  • If phones key is specified, it should be an array of objects. In the phone object only number key is required.
  • If only number is specified, then we normalize it and store as area code + number and work with these two keys instead.
  • NOTE: It may therefore help specifying both number and code to avoid ambiguity.

Both synchronous and asynchronous calls have a paid_enrichment parameter that is set to true by default. Setting it to false prevents Jobjet from searching the contact info and limits Jobjet to saving a candidate to the account (or, Jobjet merges the new candidate data with any existing candidate data).

Pricing and the creation of new candidate profiles

User credits are only charged if Jobjet finds and returns new contact information for requested candidate profiles. In other words, you only pay for the information you get, not for running the search.

If you request enrichment for a specific candidate, but there is no existing candidate profile that corresponds to the requested candidate in Jobjet, a new profile will be created in Jobjet with the newfound data. If the candidate profile does already exist in Jobjet, that existing profile will be updated with the new data automatically. 

POST /profiles/enrich - synchronous enrichment

This option is suitable for enriching a single candidate. The request should have an api key defined and it should follow the format described above. The Response will have the same format, except that it has enriched data.

Request

POST https://api.jobjet.com/profiles/enrich?api_key=f53bf423-ead8-4d02-8a8b-1baa59386a77

{
    "firstName":"Jack",
    "lastName":"Daniels",
    "phones":[
        {
            "number":"777 555 5555"
        }
    ],
    "socialProfiles":[
        {
            "profile":"https://www.linkedin.com/in/jackdaniels"
        }
    ]
}

Response

200 OK
x-credits-remain: 97
x-allowed-calls: 29
x-allowed-calls-interval: 60
x-allowed-batch-size: 50

{
    //Profile data goes here
}

POST /profles/batchEnrich - asynchronous enrichment

This enrichment allows you to enrich up to 50 candidates simultaneously and get results via callback. 

NOTE: Callback is required.

You may also want to specify an “x-search-id” header that will be passed in the request to your callback endpoint.

Request

POST https://api.jobjet.com/profiles/enrich?api_key=f53bf423-ead8-4d02-8a8b-1baa59386a77&callback=https%3A%2F%2Fmysite.com%2Fcallback
x-search-id: my-search-id

[{
    //Put profile_1 data here
},
{
    //Put profile_2 data here
}
]

Response

200 OK

Callback

When Jobjet finishes processing the request, it calls your endpoint with the following payload:

POST https://mysite.com/callback

x-credits-remain: 97
x-allowed-calls: 29
x-allowed-calls-interval: 60
x-allowed-batch-size: 50
x-search-id: my-search-id

[{
    //Profile_1 data goes here
},
{
    //Profile_2 data goes here
}


NOTE: Jobjet expects your endpoint to return a “200 OK“ response.

OPTIONS /profiles/enrich

This option allows you to check the API usage, remaining credits and API calls.

Request

OPTIONS /profiles/enrich?api_key=f53bf423-ead8-4d02-8a8b-1baa59386a77

Response

200 OK

x-credits-remain: 97
x-allowed-calls: 29
x-allowed-calls-interval: 60
x-allowed-batch-size: 50
x-search-id: my-search-id

HTTP Codes

  • 200 - Request served and response returned - responds with a JSON with people profiles
  • 202 - Request served, response is going to be delivered to the specified callback URL - responds with {"message": "Accepted. Request is being processed."}
  • 400 - Bad request, e.g. the data in the request is not valid
  • 402 - Payment required, no credits available for contact information retrieval - responds with {"error": "Not enough credits. Contact your account manager or upgrade the plan."}
  • 403 - Unauthorized, API key is inactive or doesn't exist - responds with {"error":"Unauthorized. API key is inactive."}
  • 412 - Precondition failed, usually occur when one of the limits exceeded, e.g. number of requests per minute exceeds the limit - responds with {"error": "Rate limit exceeded. Try again later."}
  • 412 - Precondition failed when batch size is exceeded - responds wth . {"error": "Batch size is exceeded. Try smaller batches."}
  • 422 - The request is syntactically correct, but has semantic errors - responds with any of the following: 1. {"error": "Specified parameters do not allow for person identification. Provide any of these parameters: firstName+lastName+email, firstName+lastName+phone or firstName+lastName+socialProfile."}; 2. {"error":"API key is missing or incorrect"}; 3. {"error": "Callback field is required."}; 4. {"error": "Callback URL is incorrect."}
  • 500 - Server-side error - responds with {"error": "Internal server error. [copy for server error]"}
  • 503 - Service unavailable, the app is in the process of upgrading - {"error":"Service Unavailable. Undergoing maintenance"}

Security

Once we generate a custom API key and hand it over to you, you are completely responsible for the security of the key. 

You understand and agree that you are responsible for maintaining the confidentiality of your key and agree not to provide it to any other person. You specifically agree that you are responsible for any actions entered through Jobjet by you or others who obtain access through you using your key. You agree that Jobjet is not responsible for any damages or losses resulting from any breach of security caused by your failure and/or the failure of other persons who obtain the key through you to maintain the confidentiality of your key. You agree to notify Jobjet immediately if you suspect that your key has been lost or stolen or that an unauthorized person has obtained access to the Service using your key.

Questions and Queries

If you have any additional questions about the Jobjet API, requesting your API key or API’s technical specifications, please reach out to the Jobjet sales team. We’re always around to answer all of your questions.

Did this answer your question?