Portal-specific data

Different posting destinations require unique data to be sent to them - for example, their own specific sector list or qualification levels.

Our posting API works to understand what Extra Field data you have sent through, and if anything is missing, idibu will request the user to fill it in via the Post Completion Page.

When using the XML API, if you wish to bypass the PCP entirely, you will need to send complete required Portal-specific data. The webservice methods documented below facilitate the acquisition of data related to Portal objects, encompassing job boards, websites, and social media platforms suitable for job advertisement placement.

Listing Portals

This method enables the listing of Portals based on appropriate filtering and ordering criteria for a given account.

Endpoint

https://ws.idibu.com/clients/json.php

Query parameters

Parameter Name	Type restrictions	Required?	Notes
hash	String	Yes	Hash of the idibu account to which the request pertains.
action	String	Yes	Must be set to UserPortal.
class	String	Yes	Must be set to Portal.
format	String	Yes	Must be set to XML.
list	String (enum) Accepted values: all - All available Portals subscribed - Portals to which the account is subscribed unsubscribed - Portals to which the account is not subscribed	Yes	Which Portals to list.

Response format

<idibu>
  <boards>
    <board id="[integer]" last_modified="[string:date]" published="["true"|"false"]" subscribed="["true"|"false"]" allows_html="["true"|"false"]">
    <!-- "id" - portal id -->
    <!-- "last_modified" - last modification date (YYYY-MM-DD HH:mm:ss) -->
    <!-- "published" - whether the portal is published ("false" means it is not possible to post - might be completely disabled or temporarily under maintenance) -->
    <!-- "subscribed" - whether the account is currently subscribed ot the portal; displays only on "true" -->
    <!-- "allows_html" - whether HTML is allowed ("false" means idibu will automatically convert Job Description to plain text) -->
      <name>[string]</name> <!-- name of the portal -->
      <description>[string]</description> <!-- descripton of the portal -->
      <tags> <!-- industries related to the Portal; can be multiple -->
        <tag>[string]</tag>
      </tags>
    </board>
  </boards>
</idibu>

---

Portal's detailed information

This method allows the retrieval of comprehensive details about a specific Portal, encompassing the essential data and extra fields required for successful postings.

Endpoint

https://ws.idibu.com/clients/json.php

Query parameters

Please maintain the order in which the parameters are listed!

Parameter Name	Type restrictions	Required?	Notes
hash	String	Yes	Hash of the idibu account to which the request pertains.
class	String	Yes	Must be set to Portal.
action	String	Yes	Must be set to showData.
boardID	Integer	Yes	ID of the Portal to show.
format	String	Yes	Must be set to XML.
country	2-letter ISO code	No	Country code for Extra Field lookup. While this parameter is not required and will not affect most Portals, it is strongly recommended to always include as some Portals use country input in order to populate or filter their location Extra Fields with matching options.
location	String	No	Location for Extra Field lookup. While this parameter is not required and will not affect most Portals, it is strongly recommended to always include as some Portals require a Location string to be specified in order to populate their location Extra Fields with matching options. If no Location is provided (or the name matches no available options), the fields may not populate and therefore prevent the posting. Please use the full text name (not ID) of the sublocation.
profileID	Integer	No	ID of the posting user. While this parameter is not required, it is strongly recommended to always include as some Extra Field values may depend on each particular user's setup. Refer to the User Management Webservice.
title	String	No	Title of the job. While this parameter is not required, it is strongly recommended to always include as some Portals use the job's title to filter or recommend some Extra Field values.

Response format

<idibu>
  <boards>
    <board id="[integer]" last_modified="[string:date]" published="["true"|"false"]" allows_html="["true"|"false"]" supports_delete="["Yes"|"No"]">
    <!-- "id" - portal id -->
    <!-- "last_modified" - last modification date (YYYY-MM-DD HH:mm:ss) -->
    <!-- "published" - whether the portal is published ("false" means it is not possible to post - might be completely disabled or temporarily under maintenance) -->
    <!-- "allows_html" - whether HTML is allowed ("false" means idibu will automatically convert Job Description to plain text) -->
    <!-- "supports_delete" - whether the portal allows deleting of already posted jobs -->
      <name>[string]</name> <!-- name of the portal -->
      <description>[string]</description> <!-- descripton of the portal -->
      <tags> <!-- industries related to the Portal; can be multiple -->
        <tag>[string]</tag>
      </tags>
      <bid>[string]</bid> <!-- default tracking code for the portal; refer to /docs/v2/webservices/settings-management/application_url_tracking.md -->
      <liveauth>["yes"|"no"]</liveauth> <!-- if set to "yes", the portal supports the LiveAuth feature; refer to /docs/v2/posting-api/LiveAuth-API.md -->
      <validators> <!-- value limits for the extra fields; refer to /docs/v2/posting-api/board-specific-fields.md#extra-field-validators -->
        <rule type="[string:enum]" control="[integer]"> <!-- type of the validator (see below) ; and a number that defines the limit -->
          <field>[string]</field> <!-- name of the extra field -->
          <message>[string]</message> <!-- error message to display if the limit is violated -->
        </rule>
      </validators>
      <durations> <!-- available posting durations (in number of days) after which the posting will automatically expire; can be multiple; no options indicate infinite duration -->
        <duration value="[integer]">[string]</duration> <!-- number of days ; and the name of the option to display -->
      </durations>
      <extrafields> <!-- all extra fields assigned to the portal; refer to /docs/v2/posting-api/board-specific-fields.md#extra-field-types -->
        <extrafield name="[string]" dynfield="[string]" description="[string]" type="[string:enum]" order="[integer]" multi="["true"|"false"]" validated="["true"|"false"]" required="["true"|"false"]">
        <!-- "name" - name of the extra field -->
        <!-- "dynfield" - name of the dynamic core field to which the field is connected; refer to /docs/v2/posting-api/dyn-vars.md -->
        <!-- "description" - friendly name to display -->
        <!-- "type" - type of the field (see below) -->
        <!-- "order" - number that controls the order in which the fields should be displayed -->
        <!-- "multi" - whether the field allows multiple options to be selected; displays only on "true" -->
        <!-- "validated" - whether the field uses a validator (see above); displays only on "true" -->
        <!-- "required" - whether the field is required or optional; displays only on "true" -->	
        <!-- refer to /docs/v2/posting-api/spec-data.md for more info on how each extra field data should be sent in the payload -->
          <data> <!-- only for "type=select" fields -->
            <option>Please select...</option> <!-- if an option has no id, it should only be displayed but not selectable -->
            <option id="[string]">[string]</option> <!-- the first string ("id") is the value to be sent in the field; the second one is the friendly name to be displayed -->
            <option id="[string]" parent="[string]">[string]</option> <!-- if the field is double-select, both "id" and "parent" values need sending -->
          </data>
        </extrafield>
      </extrafields>
      <dynfields> <!-- all dynamic core fields that the portal utilizes; refer to /docs/v2/posting-api/dyn-vars.md --> 
        <dynfield name="[string:enum]" type="[string:enum]" description="[string]"/> <!-- name of the dynamic core field ; type of the connected extra field ; friendly name of the connected extra field -->
      </dynfields>
    </board>
  </boards>
</idibu>

Extra Field Validators

Validators impose constraints on specific Extra Fields, ensuring successful postings. These include limits related to field length, content, numeric values, and data type.

Field length

• fieldMaxLength - Maximum character count
• fieldMinLength - Minimum character count
• fieldMaxWords - Maximum word count
• fieldMinWords - Minimum word count
• listHasMaxChoices - Maximum choice count (only for "type=select" multi="true" fields)
• listHasMinChoices - Minimum choice count (only for "type=select" multi="true" fields)

Field content

• fieldWithoutLinks - Restricts links in the field
• fieldWithoutEmails - Restricts email addresses in the field

Numeric fields

• intMaxSize - Maximum allowed number
• intMinSize - Minimum allowed number

Field data type

• onlyNumbers - Allows only numbers
• fieldHasProperLink - Allows valid URLs
• validUKPostCode - Allows valid UK post codes

Extra Field Types

• text - Standard text field (no newlines)
• textarea - Standard text area (newlines allowed)
• select - Dropdown field (single- or double-select with one or multiple options)
• hidden - Non-visible field without user control

Sending the Portal-specific data

Job board-specific data is provided in the posts section of the XML; each job board's data then goes under the board tag. A simple extra field section for a job board would look like this:

<posts>
  <board id="77">
    <duration days="7" />
    <extrafield name="auto_StartDate">13 feb 2009</extrafield>
  </board>
</posts>

Notice the duration tag - it is not required; however, possible values will be shown when you access the board's details using the discovery services (documented above). If no duration is provided, the user will be prompted to add it via the PCP link of a delayed posting.

The idibu system has a number of different Extra Field types:

Text and Text Area Fields

<extrafield name="ITjb_skilss">VB, Java, C#</extrafield>

Select

<extrafield name="js_Country">GBR</extrafield>

Multi Select

Should generate an array, even when it has only 1 item. Only valid format is with the item tags:

<extrafield name="auto_Category">
  <item id="7206" />
  <item id="7207" />
  <item id="7208" />
  <item id="7211" />
</extrafield>

Double Select

<extrafield name="M_dabse" parent="157">
  <item id="78" />
</extrafield>

Double Multi Select

The first selection is a single dropdown, the second is a multi-select:

<extrafield name="M_CatOpp" parent="11454">
  <item id="6" />
  <item id="11752" />
  <item id="11800" />
</extrafield>

Hidden Fields

Those fields should be ignored by the developers linking their applications to idibu's API. Those "hidden" fields are fed with data from the dynamic core fields.

Duration field

Most Portals will have an additional duration field, among other Extra Fields. Possible values can be found in the webservices documented above, and the field is required if you'd like to post without PCP. You just need to provide the number of days your post should be live from the selection available on a per-board basis.

<duration days="7" />