Portal information

This section explains how to retrieve information about Portals, which are the job boards, websites, and social media platforms where you can post job advertisements. Accessing and presenting individual Portals' data is necessary if you are building a full API integration (Direct Posting) without employing Post Completion Pages.

Additional Portal-specific data can be discovered using the Portal Management webservice.

For more information on how the Portal-specific data is utilized when creating Posts, refer to the Posts section of the jobposting XML.

Listing Portals

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

Endpoint

GET 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 Client 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. Client can only post to Portals to which their account is subscribed.

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" - the date of last breaking changes (YYYY-MM-DD HH:mm:ss); quick reposting to this Portal will be blocked for any Posts performed before this date -->
    <!-- "published" - whether the Portal is published ("false" means it is not possible to post to - might be completely disabled or temporarily under maintenance) -->
    <!-- "subscribed" - whether the Client account is currently subscribed to the Portal; displays only on "true" -->
    <!-- "allows_html" - whether HTML is allowed ("false" means idibu will automatically convert the 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 for the retrieval of comprehensive details about a specific Portal, encompassing the essential data and Extra Fields required for successful postings.

This method is designed to be used dynamically. Portal-specific data is often subject to change and idibu will not actively inform Partners or Clients about every adjustment. Ideally, the data obtained as part of this method should be requested before every posting.

Endpoint

GET 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 some Portals, it is strongly recommended to always include, as many Portals use country input in order to populate or filter their location Extra Fields with matching options.
location	String	No	Location name for Extra Field lookup. While this parameter is not required and will not affect some Portals, it is strongly recommended to always include, as many 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. For best results, provide short, broad names and avoid too much detail, e.g.: use "London" rather than "West Central London".
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" - the date of last breaking changes (YYYY-MM-DD HH:mm:ss); quick reposting to this Portal will be blocked for any Posts performed before this date -->
    <!-- "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; refer to https://docs.idibu.com/docs/v2/posting-api/delete -->
      <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 https://docs.idibu.com/docs/v2/webservices/settings-management/application_url_tracking -->
      <liveauth>[yes|no]</liveauth> <!-- if set to "yes", the Portal supports the LiveAuth feature; refer to https://docs.idibu.com/docs/v2/posting-api/liveauth-api -->
      <validators> <!-- value limits for the Extra Fields; see below for more info -->
        <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; absence of this field indicates infinite duration -->
        <duration value="[integer]">[string]</duration> <!-- number of days and the text to display -->
      </durations>
      <extrafields> <!-- all Extra Fields assigned to the Portal; see below for more info -->
        <extrafield name="[string]" dynfield="[string]" description="[string]" type="[string:enum]" order="[integer]" multi="[true|false]" validated="[true|false]" required="[true|false]">
        <!-- "name" - unique variable name of the Extra Field -->
        <!-- "dynfield" - name of the Dynamic Core Field to which the field is connected; refer to https://docs.idibu.com/docs/v2/posting-api/dynamic-core-fields -->
        <!-- "description" - friendly name (label) 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 https://docs.idibu.com/docs/v2/posting-api/posts-section 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 be treated as the top, default "nothing selected" empty item -->
            <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 (label) to be displayed -->
            <option id="[string]" parent="[string]">[string]</option> <!-- if the field is double-select, both "id" and "parent" values need sending in a specific format (see below)  -->
          </data>
        </extrafield>
      </extrafields>
      <dynfields> <!-- all Dynamic Core Fields that the Portal utilizes; refer to https://docs.idibu.com/docs/v2/posting-api/dynamic-core-fields --> 
        <dynfield name="[string:enum]" type="[string:enum]" description="[string]"/>
        <!-- "name" - name of the Dynamic Core Field --> 
        <!-- "type" - type of the connected Extra Field (see below) -->
        <!-- "description" - friendly name of the connected Extra Field -->
      </dynfields>
    </board>
  </boards>
</idibu>

Example request and response

The below response is for Portal ID 1234 - idibu Test Portal. You can generate it by accessing:

https://www.idibu.com/clients/json.php?class=Portal&action=showData&boardID=1234&format=XML&country=GB&location=London&title=Test+Job&profileID=[user-id]&hash=[client-hash]

Make sure to replace the [user-id] with a correct User ID (refer to the User Management Webservice for more info) and [client-hash] with the account's hash.

<idibu>
  <boards>
    <board id="1234" last_modified="2025-12-31 13:00:00" published="true" allows_html="true" supports_delete="Yes">
      <name><![CDATA[idibu Test Portal]]></name>
      <description><![CDATA[This is an internal idibu Portal meant for developers to test their API postings. <br/><br/> For more information, refer to <a href="https://docs.idibu.com/docs/v2/posting-api/idibu-test-portal" target="_blank">this article</a>.]]></description>
      <tags></tags>
      <bid>bvm</bid>
      <liveauth>no</liveauth>
      <details><![CDATA[Please consult <a href="https://docs.idibu.com/docs/v2/posting-api/idibu-test-portal" target="_blank">this article</a> for more information on how to set up and use this Portal.]]></details>
      <validators>
        <rule type="fieldMaxLength" control="50">
          <field>title</field>
          <message><![CDATA[Job title can't be longer than 50 characters.]]></message>
        </rule>
        <rule type="fieldMinLength" control="4">
          <field>reference</field>
          <message><![CDATA[Job reference must be longer than 3 characters.]]></message>
        </rule>
        <rule type="fieldMaxWords" control="20">
          <field>duration</field>
          <message><![CDATA[Duration can't have more than 20 words.]]></message>
        </rule>
        <rule type="fieldMinWords" control="10">
          <field>description</field>
          <message><![CDATA[Job Description must have at least 10 words.]]></message>
        </rule>
        <rule type="listHasMaxChoices" control="3">
          <field>idibutest_multi</field>
          <message><![CDATA[Multi dropdown allows a maximum of 3 options.]]></message>
        </rule>
        <rule type="fieldWithoutLinks" control="1">
          <field>idibutest_area</field>
          <message><![CDATA[Text area cannot contain links or emails.]]></message>
        </rule>
        <rule type="fieldWithoutEmails" control="1">
          <field>idibutest_area</field>
          <message><![CDATA[Text area cannot contain links or emails.]]></message>
        </rule>
      </validators>
      <durations>
        <duration value="7">7 days</duration>
        <duration value="6">6 days</duration>
        <duration value="5">5 days</duration>
        <duration value="4">4 days</duration>
        <duration value="3">3 days</duration>
        <duration value="2">2 days</duration>
        <duration value="1">1 day</duration>
      </durations>
      <extrafields>
        <extrafield name="idibutest_text" description="Text field" type="text" order="30"/>
        <extrafield name="idibutest_area" description="Text area" type="textarea" order="40" validated="true"/>
        <extrafield name="idibutest_select" description="Single dropdown" type="select" order="50">
          <data>
            <option>Please select...</option>
            <option id="1">One</option>
            <option id="2">Two</option>
            <option id="3">Three</option>
            <option id="4">Four</option>
            <option id="5">Five</option>
          </data>
        </extrafield>
        <extrafield name="idibutest_multi" description="Multi dropdown" type="select" order="60" validated="true" multi="true">
          <data>
            <option id="one">One</option>
            <option id="two">Two</option>
            <option id="three">Three</option>
            <option id="four">Four</option>
            <option id="five">Five</option>
          </data>
        </extrafield>
        <extrafield name="idibutest_double" description="Double dropdown" type="select" order="70">
          <data>
            <option>Please select...</option>
            <option id="p1">Parent 1</option>
            <option id="c11" parent="p1">Child 1-1</option>
            <option id="c12" parent="p1">Child 1-2</option>
            <option id="c13" parent="p1">Child 1-3</option>
            <option id="p2">Parent 2</option>
            <option id="c21" parent="p2">Child 2-1</option>
            <option id="c22" parent="p2">Child 2-2</option>
            <option id="c23" parent="p2">Child 2-3</option>
            <option id="p3">Parent 3</option>
            <option id="c31" parent="p3">Child 3-1</option>
            <option id="c32" parent="p3">Child 3-2</option>
            <option id="c33" parent="p3">Child 3-3</option>
          </data>
        </extrafield>
        <extrafield name="idibutest_dmulti" description="Double multiselect" type="select" order="80" multi="true">
          <data>
            <option>Please select...</option>
            <option id="pm1">Parent 1</option>
            <option id="cm11" parent="pm1">Child 1-1</option>
            <option id="cm12" parent="pm1">Child 1-2</option>
            <option id="cm13" parent="pm1">Child 1-3</option>
            <option id="pm2">Parent 2</option>
            <option id="cm21" parent="pm2">Child 2-1</option>
            <option id="cm22" parent="pm2">Child 2-2</option>
            <option id="cm23" parent="pm2">Child 2-3</option>
            <option id="pm3">Parent 3</option>
            <option id="cm31" parent="pm3">Child 3-1</option>
            <option id="cm32" parent="pm3">Child 3-2</option>
            <option id="cm33" parent="pm3">Child 3-3</option>
          </data>
        </extrafield>
        <extrafield name="idibutest_url" dynfield="app_url" description="Application URL" type="hidden" order="100"/>
        <extrafield name="idibutest_osal" dynfield="salaryOverride" description="Salary Override" type="hidden" order="110"/>
        <extrafield name="idibutest_odat" dynfield="startDateOverride" description="Start Date Override" type="hidden" order="120"/>
      </extrafields>
      <dynfields>
        <dynfield name="app_url" type="text" description="Application URL (Optional)"/>
        <dynfield name="salaryOverride" type="text" description="Salary Text Override (Optional)"/>
        <dynfield name="startDateOverride" type="text" description="Start Date Desc (Optional)"/>
      </dynfields>
    </board>
  </boards>
</idibu>

Extra Fields

Most Portals will have an <extrafields> element in the response, which will list a number of <extrafield> elements. This data represents fields specific to the given Portal, not covered by idibu's core data, and needs to be provided (in a different format) as part of the Posts section of the jobposting XML.

Attributes

Each <extrafield> element has several attributes that provide important information about the field:

• name: The name of the Extra Field (used as board/extrafield:name in the Posts section of the jobposting XML).
• dynfield: The name of the Dynamic Core Field to which the field connects. See the Dynamic Core Fields documentation for more information.
• description: A user-friendly name for displaying the field in the UI.
• type: The type of the field:
  • text: Standard text field (no newlines).
  • textarea: Standard text area (newlines allowed).
  • select: Dropdown field (single- or double-select; accepts multiple options if multi="true").
  • hidden: Invisible field meant to be outside of user control.
• order: A number that controls the order in which the fields should be displayed in the UI.
• multi: Indicates whether the field allows multiple options to be selected (true or false).
• validated: Indicates whether the field uses a validator (true or false). See Extra Field Validators below.
• required: Indicates whether the field is mandatory (true) or optional (false). Failure to provide valid data in all required Extra Fields will result in the creation of a Post Completion Page.

Validators

Extra Fields can have validators, which impose constraints on the data to ensure successful postings. The <validators> element can contain a number of <rule> elements.

If present, a <rule> element will consist of two attributes:

• type - the values can apply rules for:
  • Field length:
    • fieldMaxLength: Maximum character count.
    • fieldMinLength: Minimum character count.
    • fieldLengthIs: Exact character count.
    • fieldMaxWords: Maximum word count.
    • fieldMinWords: Minimum word count.
    • listHasMaxChoices: Maximum choice count (for "type=select" multi="true" fields).
    • listHasMinChoices: Minimum choice count (for "type=select" multi="true" fields).
  • Numeric fields:
    • intMaxSize: Maximum allowed number.
    • intMinSize: Minimum allowed number.
  • Field content:
    • fieldWithoutLinks: Disallows links in the field.
    • fieldWithoutEmails: Disallows email addresses in the field.
  • Field data type:
    • onlyNumbers: Allows only numbers (no decimals).
    • onlyCurrencyNumbers: Allows only numbers (up to two decimals allowed - use dot).
    • fieldHasProperLink: Allows only a valid URL.
    • validUKPostCode: Allows only a valid UK postcode.
• control - a number that defines the limit; if no numeric limit is imposed, will be set to 1.

Each <rule> element will also have the following two sub-elements:

• <field> - the corresponding Extra Field's name.
• <message> - a user-friendly message to display in the UI when the limit is violated for the field.

Select-type fields

Extra Fields that are set as type=select will have an additional <data> element, containing a list of <option> elements. Each <option> element will have an id attribute - which indicates the value to send as the id attribute of the <item> element in the Posts section of the jobposting XML - and a value specifying the user-friendly name of the option to display.

This type of Extra Fields can actually span four different field subtypes, each functioning differently and requiring different handling in the UI.

Single-select fields

Identified by:

• type=select
• multi=false
• no parent attributes in any of the <option> elements

These fields will always have an empty <option> element, without the id attribute - this element is meant to be displayed as the top, pre-selected option if nothing has been selected by the user yet.

id attribute of one of these fields' <option> elements needs to be sent as the id attribute of the <item> element (only one) under the given <extrafield> element in the jobposting XML.

Example:

Single-select field in the API response:

<extrafield name="idibutest_select" description="Single dropdown" type="select" order="50">
  <data>
    <option>Please select...</option>
    <option id="1">One</option>
    <option id="2">Two</option>
    <option id="3">Three</option>
    <option id="4">Four</option>
    <option id="5">Five</option>
  </data>
</extrafield>

Sending the single-select field's value in the jobposting XML:

</extrafield name="idibutest_select">
  <item id="3" />
</extrafield>

Multi-select fields

Identified by:

• type=select
• multi=true
• no parent attributes in any of the <option> elements

Contrary to single-select, these fields will not have an empty <option> element.

id attributes of one or more of these fields' <option> elements need to be sent as the id attributes of the <item> elements (can be multiple) under the given <extrafield> element in the jobposting XML.

Example:

Multi-select field in the API response:

<extrafield name="idibutest_multi" description="Multi dropdown" type="select" order="60" validated="true" multi="true">
  <data>
    <option id="one">One</option>
    <option id="two">Two</option>
    <option id="three">Three</option>
    <option id="four">Four</option>
    <option id="five">Five</option>
  </data>
</extrafield>

Sending the multi-select field's values in the jobposting XML:

</extrafield name="idibutest_multi">
  <item id="one" />
  <item id="three" />
  <item id="five" />
</extrafield>

Double-select fields

• type=select
• multi=false
• parent attributes present for some of the <option> elements

Similar to single-select, there will always be an empty <option> element, without the id attribute, meant to be displayed as the top, pre-selected parent option if nothing has been selected by the user yet.

• <option> elements without the parent attribute are parents - their id attribute is meant to be sent as the parent attribute (only one allowed) of the <extrafield> element representing the field in the jobposting XML.
• <option> elements that include the parent attribute are children - the parent attribute identifies the id value of their parent. Their id attribute is meant to be sent as the id attribute of the <item> element (only one allowed) under the given <extrafield> element in the jobposting XML. The child value id sent this way must belong to its parent attribute.
• Parent <option> cannot be sent alone - a child id value must always be sent, and its appropriate parent assigned as the parent attribute.

Example:

Double-select field in the API response:

<extrafield name="idibutest_double" description="Double dropdown" type="select" order="70">
  <data>
    <option>Please select...</option>
    <option id="p1">Parent 1</option>
    <option id="c11" parent="p1">Child 1-1</option>
    <option id="c12" parent="p1">Child 1-2</option>
    <option id="p2">Parent 2</option>
    <option id="c21" parent="p2">Child 2-1</option>
    <option id="c22" parent="p2">Child 2-2</option>
  </data>
</extrafield>

Sending the double-select field's value in the jobposting XML:

<extrafield name="idibutest_double" parent="p2">
  <item id="c21" />
</extrafield>

Double-multi-select fields

• type=select
• multi=true
• parent attributes present for some of the <option> elements

Similar to double-select, there will always be an empty <option> element, without the id attribute, meant to be displayed as the top, pre-selected parent option if nothing has been selected by the user yet.

• <option> elements without the parent attribute are parents - their id attribute is meant to be sent as the parent attribute (only one allowed) of the <extrafield> element representing the field in the jobposting XML.
• <option> elements that include the parent attribute are children - the parent attribute identifies the id value of their parent. Their id attributes are meant to be sent as the id attributes of the <item> elements (can be multiple) under the given <extrafield> element in the jobposting XML. The children id values sent this way must belong to their parent attribute - meaning that, even though multiple children values can be specified, they all must belong under a single parent only.
• Parent <option> cannot be sent alone - children id values must always be sent, and their appropriate parent (only one allowed) assigned as their parent attribute.

Example:

Double-multi-select field in the API response:

<extrafield name="idibutest_dmulti" description="Double multiselect" type="select" order="80" multi="true">
  <data>
    <option>Please select...</option>
    <option id="pm1">Parent 1</option>
    <option id="cm11" parent="pm1">Child 1-1</option>
    <option id="cm12" parent="pm1">Child 1-2</option>
    <option id="cm13" parent="pm1">Child 1-3</option>
    <option id="pm2">Parent 2</option>
    <option id="cm21" parent="pm2">Child 2-1</option>
    <option id="cm22" parent="pm2">Child 2-2</option>
    <option id="cm23" parent="pm2">Child 2-3</option>
  </data>
</extrafield>

Sending the double-multi-select field's values in the jobposting XML:

<extrafield name="idibutest_dmulti" parent="pm1">
  <item id="cm11" />
  <item id="cm12" />
  <item id="cm13" />
</extrafield>

Check here for a complete example of sending Extra Fields' data in the API jobposting XML.