Addresses

Resource type: address

Outputs information from address records.

Use the parameter recordids to specify the desired addresses. Without this parameter, all addresses are output.

The parameters filterid and filter can also be used to restrict the selection of addresses. With self-created filters you could output the last changed addresses for example.

All fields specified in the enterprise administration are valid here and are passed as elements of an array in the parameter data. Each parameter is returned with the corresponding value of the record.

Contact details (telephone, fax, e-mail) are returned like this: „<identifier><typ>__<id>“.

The parameters are followed by several example calls for different applications: reading out address data, reading out the addresses changed in the last 30 days via a filter, and querying the URL for the passport photo.

Parameter:

  • data
    ARRAY

    • (individually)
    • phone
      all phonebook entries except with type “mobile”
    • mobile
      all phone book entries with type “mobile”
    • fax
      all phone book entries with type “fax”
    • email
      all phone book entries with type “email”
    • defaultphone
      like phone, but only returns the record marked as default
    • defaultfax
      like fax, but only returns the record marked as default
    • defaultemail
      like email, but only returns the record marked as default
    • imageUrl
      image URL (pass photo) of the address.
  • recordids
    ARRAY. Address IDs. Can be used if one or more than one record should be read, but not all.
  • filterid
    INTEGER. Filter ID. This parameter can also be used to restrict the selection of address data records via address filters created in enterprise. The filter IDs of your created filters can be read out via the API call Filter. Further information on filters can be found in our online help.
  • filter
    OBJECT. Key: field, value: array of objects with filter expressions in the format "status": [{"op": "=", "val": 1}]. With op you specify the operator. Possible values for op are the following SQL operators:
    is or =, >, <, >=, <=, != or <>, between, like, not like, in, not in

    For the operator like the value % can be specified as a placeholder.

    With val you specify the value which should be applied to the filtering. The individual filter expressions are linked with the AND operation.

  • listlimit
    INTEGER. Maximum number of addresses in the list. Default value: 20, Maximum: 500.
  • listoffset
    INTEGER. Offset of the list, that means from which data record onwards the list should be output.
  • sortby
    STRING. Field to sort by.
  • sortorder
    STRING. Possible values: ASC or DESC. Ascending or descending.
  • formatoutput
    BOOLEAN. Default = false. Enable formatted output. If set to true, the contents of the single- and multi-select fields (column content in the enterprise administration on tabs singleselect und multiselect) instead of the field (column field in the administration on tabs singleselect und multiselect) are outputted. With formatoutput false, multiselect values are seperated with pipes.
  • outputlanguage
    STRING. Output language. E.g. the contents of the single- and multi-select fields are output in the specified language. Parameter formatoutput must be set to true.
  • extendedclaim
    STRING. Mandatory for marketplace providers. Not relevant for all other users. To verify the user which uses the marketplace return the “apiClaim” parameter from the service call as “extendedclaim”. User rights are then observed by the marketplace provider API user.

Example: Read address data

...
{
    "actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
    "resourceid": "",
    "identifier": "",
    "resourcetype": "address",
    "parameters": {
        "data": [
            "Briefanrede",
            "Vorname",
            "Name",
            "Land",
            "Ort",
            "Plz",
            "Strasse"
        ],
        "filter": {
            "Vorname": [
                {
                    "op": "=",
                    "val": "Max"
                }
            ]
        },
        "sortby": "Strasse",
        "sortorder": "DESC"
    }
}
...

Response: Read address data

  • (individuell)

If the fields defaultphone, defaultemail or defaultfax have been requested, they will also be output separately in the same notation.

{
    "status": {
        "code": 200,
        "errorcode": 0,
        "message": "OK"
    },
    "response": {
        "results": [
            {
                "actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
                "resourceid": "",
                "resourcetype": "address",
                "cacheable": true,
                "identifier": "",
                "data": {
                    "meta": {
                        "cntabsolute": 2
                    },
                    "records": [
                        {
                            "id": 10505,
                            "type": "address",
                            "elements": {
                                "id": 10505,
                                "Briefanrede": "Sehr geehrter Herr Mustermann,",
                                "Vorname": "Max",
                                "Name": "Mustermann",
                                "Land": "Deutschland",
                                "Ort": "Musterstadt",
                                "Plz": "123456",
                                "Strasse": "Musterrstra\u00dfe"
                            }
                        },
                        {
                            "id": 10509,
                            "type": "address",
                            "elements": {
                                "id": 10509,
                                "Briefanrede": "Sehr geehrter Herr Mustermann,",
                                "Vorname": "Max",
                                "Name": "Mustermann",
                                "Land": "Deutschland",
                                "Ort": "Musterhausen",
                                "Plz": "50000",
                                "Strasse": "Mustergasse"
                            }
                        },
                    ]
                },
                "status": {
                    "errorcode": 0,
                    "message": "OK"
                }
            }
        ]
    }
}

Example: Read out the addresses changed in the last 30 days via the filter

...
"actions":[
    {
        "actionid":"urn:onoffice-de-ns:smart:2.5:smartml:action:read",
        "resourceid":"",
        "identifier":"",
        "resourcetype":"address",
        "parameters":{
            "filterid":102,
            "data":[
                "Briefanrede",
                "Vorname",
                "Name",
                "Strasse",
                "Plz",
                "Ort",
                "Land",
                "Email"
            ]
        }
    }
]
...

The expression used in the filter is: ((`adressen`.`Status` = '1' AND `adressen`.`Aenderung` >= DATE_SUB(NOW(), INTERVAL 30 DAY) AND `adressen`.`Aenderung` <= NOW()) AND `adressen`.`Aenderung` >= DATE_SUB(NOW(), INTERVAL 30 DAY) AND `adressen`.`Aenderung` <= NOW() )

Example: Query the URL to the passport photo (top left in an address record)

...
"actions":[
    {
        "actionid":"urn:onoffice-de-ns:smart:2.5:smartml:action:read",
        "resourceid":"",
        "identifier":"",
        "resourcetype":"address",
        "parameters":{
            "recordids":[32],
            "data":[
                "Name",
                "Vorname",
                "imageUrl"
            ]
        }
    }
]
...