==================== Address Book Service ==================== .. tip:: `OpenAPI Reference `__ The Address Book Service is part of **netfiles Send**. It stores addresses so users can easily send files to frequent contacts. With this service, you can pick a user to send files to, create, edit or delete users and contacts, and import and export contacts. Basically everything you can expect from an Address Book. .. Add image of Address Book The exhaustive list of endpoints and how to use them to build Address Book automations is below. The endpoints you can use are: .. list-table:: :header-rows: 1 :widths: 10 45 45 * - METHOD - PATH - SUMMARY * - GET - /v1/send/ab/{sendId} - Get contacts and groups * - POST - /v1/send/ab/{sendId}/contact/add - Add contacts * - DELETE - /v1/send/ab/{sendId}/contact/delete/{contactId} - Delete contact * - PATCH - /v1/send/ab/{sendId}/contact/edit - Edit contact * - GET - /v1/send/ab/{sendId}/contact/image/{contactId} - Get contact image * - DELETE - v1/send/ab/{sendId}/contact/image/{contactId} - Delete contact image * - POST - /v1/send/ab/{sendId}/contact/image/{contactId} - Set contact image * - POST - /v1/send/ab/{sendId}/group/add - Add Contact Group * - POST - /v1/send/ab/{sendId}/group/add-contacts - Add contacts to group * - DELETE - /v1/send/ab/{sendId}/group/delete/{contactGroupId} - Delete contact group * - PATCH - /v1/send/ab/{sendId}/group/edit - Edit contact group * - POST - /v1/send/ab/{sendId}/group/remove-contacts - Remove contacts from a group * - POST - /v1/send/ab/{sendId}/import - Import contacts Get Contacts and Groups ======================= `GET /v1/send/ab/{sendId}` This endpoint returns all the contacts and groups of a given `NFSend id`. Access is only allowed to own `NFSend id`. For this operation, you will use a `sendId` string which will return a json file with contacts and groups, including... .. Whose id? What is the NFSend id? What does a contact look like? Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- `sendId`: string, required. .. What is a sendId, where can I find it and what format must it have? Responses --------- 200: A successful response. If sucessful, this operation returns a json file with `contacts` and `contactGroups`. Contacts are an array of objects (A Contact of an addressbook inside a netfiles send Product) Contact Groups are an array of objects (pbContactGroup) .. code-block:: json { "contacts": [ { "id": "string", "email": "string", "language": "LANGUAGE_UNSPECIFIED", "salutation": "SALUTATION_UNSPECIFIED", "title": "string", "firstName": "string", "lastName": "string", "phoneNr": "string", "locale": "LOCALE_UNSPECIFIED", "hasPhoto": true, "userTitle": "string", "base64Img": "string", "groupIds": [ "string" ] } ], "contactGroups": [ { "id": "string", "name": "string", "title": "string" } ] } 400: Invalid identifier provided. This means... To fix, do... 401: Returned when the user is not logged in. Returned when the user is not logged in. To resolve, please log in. 403: Returned when the user does not have permission to access the resource. Returned when the user does not have permission to access the resource. To resolve, please... 404: Returns when the item was not found or user doesn't have access to it. Returns when the item was not found or user doesn't have access to it. To fix please... 500: Server error. Server error. In this case,... default: An unexpected error response. This is an execpected error. It happens sometimes. Try again. Add Contacts ============ `POST /v1/send/ab/{sendId}/contact/add` This endpoint adds a new contact to a current user's address book. .. Include image of what the Contacts in a dummy address book Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- `sendID`: string, required .. What is a sendId, where can I find it and what format must it have? Query Parameters ---------------- contrat.id: string .. What is this? contact.email: string This referes to the contact's email address. contact.language: string, enum You can choose a contact language between ``LANGUAGE_UNSPECIFIED``, ``LANGUAGE_EN``, ``LANGUAGE_DE``, ``LANGUAGE_FR``, ``LANGUAGE_ES``, ``LANGUAGE_IT``, ``LANGUAGE_PL``, ``LANGUAGE_NL``, ``LANGUAGE_SV``, ``LANGUAGE_TR``, ``LANGUAGE_PT``, and ``LANGUAGE_HU``. The default language is ``LANGUAGE_UNSPECIFIED``. values - ``LANGUAGE_UNSPECIFIED`` - ``LANGUAGE_EN`` - ``LANGUAGE_DE`` - ``LANGUAGE_FR`` - ``LANGUAGE_ES`` - ``LANGUAGE_IT`` - ``LANGUAGE_PL`` - ``LANGUAGE_NL`` - ``LANGUAGE_SV`` - ``LANGUAGE_TR`` - ``LANGUAGE_PT`` - ``LANGUAGE_HU`` contact.salutation: string, enum Salutations, how the user is greeted, can be ``SALUTATION_UNSPECIFIED``, ``SALUTATION_NONE``, ``SALUTATION_MR``, and ``SALUTATION_MS``. The default salutation is ``SALUTATION_UNSPECIFIED``. .. How does this interact with the languages? values - ``SALUTATION_UNSPECIFIED`` - ``SALUTATION_NONE`` - ``SALUTATION_MR`` - ``SALUTATION_MS`` contact.title: string This refers to the user's title, such as Master, Doctor, or Prime Minister. contact.firstName: string This referes to the user's first name. contact.lastName: string This refers to the user's family or last name. contact.phoneNr: string This refers to the user's phone number. contact.locale: string, enum Locales can be ``LOCALE_UNSPECIFIED``, ``LOCALE_EN_GB``, ``LOCALE_EN_US``, ``LOCALE_FR_FR``, ``LOCALE_ES_ES``, ``LOCALE_IT_IT``, ``LOCALE_PL_PL``, ``LOCALE_NL_NL``, ``LOCALE_SV_SV``, ``LOCALE_TR_TR``, ``LOCALE_PT_BR``, ``LOCALE_DE_DE``, ``LOCALE_DE_AT``, ``LOCALE_DE_CH``, or ``LOCALE_HU_HU``. The default contact.local is ``LOCALE_UNSPECIFIED``. They refer to... values - ``LOCALE_UNSPECIFIED`` - ``LOCALE_EN_GB`` - ``LOCALE_EN_US`` - ``LOCALE_FR_FR`` - ``LOCALE_ES_ES`` - ``LOCALE_IT_IT`` - ``LOCALE_PL_PL`` - ``LOCALE_NL_NL`` - ``LOCALE_SV_SV`` - ``LOCALE_TR_TR`` - ``LOCALE_PT_BR`` - ``LOCALE_DE_DE`` - ``LOCALE_DE_AT`` - ``LOCALE_DE_CH`` - ``LOCALE_HU_HU`` contact.hasPhoto: boolean Here you can choose whether a contact has a photo or not. The values are ``true`` or ``false``. contact.userTitle: string .. what is this? contact.base64Img: string Only for backend import contacts .. What does this mean? contact.groupIds : array of strings This parameter can be empty, but you should repeat the parameter for each value. .. Example? Responses --------- 200: A successful response. If sucessful, the call retruns a json file with a Contact of an addressbook inside a netfiles send Product. .. code-block:: json { "contact": { "id": "string", "email": "string", "language": "LANGUAGE_UNSPECIFIED", "salutation": "SALUTATION_UNSPECIFIED", "title": "string", "firstName": "string", "lastName": "string", "phoneNr": "string", "locale": "LOCALE_UNSPECIFIED", "hasPhoto": true, "userTitle": "string", "base64Img": "string", "groupIds": [ "string" ] } } 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered. Delete Contact ============== `DELETE /v1/send/ab/{sendId}/contact/delete/{contactId}` Deletes a current user's contact. .. Whose id? What is the NFSend id? Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- sendId: string, required .. What is a sendId, where can I find it and what format must it have? contactId: string, required .. What is this? Responses --------- 200: A successful response. 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered. Edit Contacts ============= `PATCH /v1/send/ab/{sendId}/contact/edit` This endpoint is used to edit (or patch) the contact information of a current user. .. What does a contact look like? Is this the user's contact info or a contact from a different person? Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- sendId: string, required .. What is a sendId, where can I find it and what format must it have? Query Parameters ---------------- contact.id: string .. What is this? contact.email: string contact.language: string, enum You can choose a contact language between ``LANGUAGE_UNSPECIFIED``, ``LANGUAGE_EN``, ``LANGUAGE_DE``, ``LANGUAGE_FR``, ``LANGUAGE_ES``, ``LANGUAGE_IT``, ``LANGUAGE_PL``, ``LANGUAGE_NL``, ``LANGUAGE_SV``, ``LANGUAGE_TR``, ``LANGUAGE_PT``, and ``LANGUAGE_HU``. The default language is ``LANGUAGE_UNSPECIFIED``. values - ``LANGUAGE_UNSPECIFIED`` - ``LANGUAGE_EN`` - ``LANGUAGE_DE`` - ``LANGUAGE_FR`` - ``LANGUAGE_ES`` - ``LANGUAGE_IT`` - ``LANGUAGE_PL`` - ``LANGUAGE_NL`` - ``LANGUAGE_SV`` - ``LANGUAGE_TR`` - ``LANGUAGE_PT`` - ``LANGUAGE_HU`` contact.salutation: string, enum Salutations, how the user is greeted, can be ``SALUTATION_UNSPECIFIED``, ``SALUTATION_NONE``, ``SALUTATION_MR``, and ``SALUTATION_MS``. The default salutation is ``SALUTATION_UNSPECIFIED``. .. How does this interact with the languages? values - ``SALUTATION_UNSPECIFIED`` - ``SALUTATION_NONE`` - ``SALUTATION_MR`` - ``SALUTATION_MS`` contact.title: string This refers to the user's title, such as Master, Doctor, or Prime Minister. contact.firstName: string This referes to the user's first name. contact.lastName: string This refers to the user's family or last name. contact.phoneNr: string This refers to the user's phone number. contact.locale: string, enum Locales can be ``LOCALE_UNSPECIFIED``, ``LOCALE_EN_GB``, ``LOCALE_EN_US``, ``LOCALE_FR_FR``, ``LOCALE_ES_ES``, ``LOCALE_IT_IT``, ``LOCALE_PL_PL``, ``LOCALE_NL_NL``, ``LOCALE_SV_SV``, ``LOCALE_TR_TR``, ``LOCALE_PT_BR``, ``LOCALE_DE_DE``, ``LOCALE_DE_AT``, ``LOCALE_DE_CH``, or ``LOCALE_HU_HU``. The default contact.local is ``LOCALE_UNSPECIFIED``. They refer to... values - ``LOCALE_UNSPECIFIED`` - ``LOCALE_EN_GB`` - ``LOCALE_EN_US`` - ``LOCALE_FR_FR`` - ``LOCALE_ES_ES`` - ``LOCALE_IT_IT`` - ``LOCALE_PL_PL`` - ``LOCALE_NL_NL`` - ``LOCALE_SV_SV`` - ``LOCALE_TR_TR`` - ``LOCALE_PT_BR`` - ``LOCALE_DE_DE`` - ``LOCALE_DE_AT`` - ``LOCALE_DE_CH`` - ``LOCALE_HU_HU`` .. does this mean where the user is located? contact.hasPhoto: boolean .. what is this? contact.userTitle: string .. what is this? contact.base64Img: string Only for backend import contacts .. What does this mean? contact.groupIds : array of strings This parameter can be empty, but you should repeat the parameter for each value. .. Example? Responses --------- 200: A successful response. If sucessful, the user's contact will be edited. .. correct? .. code-block:: json { "contact": { "id": "string", "email": "string", "language": "LANGUAGE_UNSPECIFIED", "salutation": "SALUTATION_UNSPECIFIED", "title": "string", "firstName": "string", "lastName": "string", "phoneNr": "string", "locale": "LOCALE_UNSPECIFIED", "hasPhoto": true, "userTitle": "string", "base64Img": "string", "groupIds": [ "string" ] } } 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered. Get Contact Image ================== `GET /v1/send/ab/{sendId}/contact/image/{contactId}` This endpoint returns the profile imagem of the current user's given contact. .. Whose contact image is being retrieved? Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- sendId: string, required .. What is a sendId, where can I find it and what format must it have? contactId: string, required .. What is the contactId? Responses --------- 200: A successful response. If sucessful, this operation returns the user's profile image, including its binary data. .. code-block:: jason { "image": { "imageType": "PROFILE_IMAGE_TYPE_UNSPECIFIED", "imageData": "string" } } 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered. Delete Contact Image ==================== `DELETE /v1/send/ab/{sendId}/contact/image/{contactId}` This endpoint deletes a current user's given contact profile image. Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- sendId: string, required .. What is a sendId, where can I find it and what format must it have? contactId: string, required .. What is a contactId? Responses --------- 200: A successful response. 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered. Set Contact Image ================= `POST /v1/send/ab/{sendId}/contact/image/{contactId}` Sets the profile image of a given contact of the current user .. Whose id? What is the NFSend id? Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- sendId: string, required .. What is a sendId, where can I find it and what format must it have? contactId: string, required Body Parameters --------------- body: json, required Represents a user's profile image of a user, including its binary data. Responses --------- 200: A successful response. If sucessful, ... .. code-block:: json { "image": { "imageType": "PROFILE_IMAGE_TYPE_UNSPECIFIED", "imageData": "string" } } 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered. Add Contact Group ================= `POST /v1/send/ab/{sendId}/group/add` Adds a new contact group to the current user's address book Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- sendId: string, required .. What is a sendId, where can I find it and what format must it have? Query Parameters ---------------- contactGroup.id: string .. what is it? contactGroup.name: string .. what is it? contactGroup.title: string .. what is it? Responses --------- 200: A successful response. If sucessful, retrieves a Group of an addressbook inside a netfiles send Product. .. code-block:: json { "contactGroup": { "id": "string", "name": "string", "title": "string" } } 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered. Add Contacts to Group ===================== `POST /v1/send/ab/{sendId}/group/add-contacts` Adds a contact list to the current user's specificied group. Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- sendId: string, required .. What is a sendId, where can I find it and what format must it have? Query Parameters ---------------- contactIds : array of strings Repeat the parameter for each value. .. How are structured? contactGroupIds : array of strings Repeat the parameter for each value. .. How are structured? Responses --------- 200: A successful response. If sucessful, adds an array of contacts of an addressbook inside a netfiles send Product .. code-block:: json { "contacts": [ { "id": "string", "email": "string", "language": "LANGUAGE_UNSPECIFIED", "salutation": "SALUTATION_UNSPECIFIED", "title": "string", "firstName": "string", "lastName": "string", "phoneNr": "string", "locale": "LOCALE_UNSPECIFIED", "hasPhoto": true, "userTitle": "string", "base64Img": "string", "groupIds": [ "string" ] } ] } 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered. Delete Contact Group ==================== `DELETE /v1/send/ab/{sendId}/group/delete/{contactGroupId}` Deletes a contact group to the current user's address book. Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- sendId: string, required .. What is a sendId, where can I find it and what format must it have? contactGroupId: string, required .. Where to find contact group id? does the dev make it up? Responses --------- 200: A successful response. 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered. Edit Contact Group ================== `EDIT /v1/send/ab/{sendId}/group/edit` Edits (or patches) a contact group in the current user's address book. Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- sendId: string, required .. What is a sendId, where can I find it and what format must it have? Query Parameters ---------------- contactGroup.id: string .. explanation contactGroup.name: string .. explanation contactGroup.title: string .. explanation Responses --------- 200: A successful response. If sucessful, returns a Group of an addressbook inside a netfiles send Product. .. code-block:: json { "contacts": [ { "id": "string", "email": "string", "language": "LANGUAGE_UNSPECIFIED", "salutation": "SALUTATION_UNSPECIFIED", "title": "string", "firstName": "string", "lastName": "string", "phoneNr": "string", "locale": "LOCALE_UNSPECIFIED", "hasPhoto": true, "userTitle": "string", "base64Img": "string", "groupIds": [ "string" ] } ], "errorCount": 0 } 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered. Remove Contacts From Group ========================== `POST /v1/send/ab/{sendId}/group/remove-contacts` Removes a contact from a given group of the current user's address book. .. Why is it a POST endpoint if we are removing a contact? Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- sendId: string, required .. What is a sendId, where can I find it and what format must it have? Query Parameters ---------------- contactIds: array of strings Repeat the parameter for each value. .. How should it look? contactGroupIds: array of strings Repeat the parameter for each value. .. How should it look? Responses --------- 200: A successful response. 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered. Import Contacts =============== `POST /v1/send/ab/{sendId}/import` Imports a list of new contacts from an Excel or VCS file into the address book of the current user. .. What format should the file have? Authorizations -------------- ApiKeyAuth .. How does this work? Parameters ---------- sendId: string, required .. What is a sendId, where can I find it and what format must it have? Body ---- body: json, required Request to import contacts with vcard or excel format .. How should this object be? Responses --------- 200: A successful response. If sucessful, returns an Contacts from an addressbook inside a netfiles send Product .. code-block:: json { "contacts": [ { "id": "string", "email": "string", "language": "LANGUAGE_UNSPECIFIED", "salutation": "SALUTATION_UNSPECIFIED", "title": "string", "firstName": "string", "lastName": "string", "phoneNr": "string", "locale": "LOCALE_UNSPECIFIED", "hasPhoto": true, "userTitle": "string", "base64Img": "string", "groupIds": [ "string" ] } ], "errorCount": 0 } 400: Invalid identifier provided. 401: User is not logged in. 403: User does not have permission to access the resource. 404: Item not found or user doesn't have access to it. 500: Server error. default: An unexpected error ocurrered.