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>“.

In addresses, estates and other modules you can set relations like e.g. tenant, buyer, owner, contact person, estate units etc. These relations are not queried and set via estate or address calls, but this information is queried or set via the API calls “Create, Modify, Delete and Get relations”.

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.
    Fields that represent, for example, prices, areas, quantities, are also returned with the corresponding unit (€, qm² etc).
  • 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.
  • countryIsoCodeType
    STRING. Works in combination with the field Land (country). The parameter countryIsoCodeType causes the output of the field Land to be displayed in ISO-3166-2 or ISO-3166-3. Valid values are ISO-3166-2 and ISO-3166-3. If the parameter is not set or the value of the parameter invalid, the country is displayed in full text.

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"
            ]
        }
    }
]
...