Referência da API REST de Contatos do Outlook (versão 1.0)

Aplica-se a: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Observação

A versão 1.0 da API REST do Outlook está sendo preterida. A partir de 1º de novembro de 2018, os aplicativos não poderão mais usar a Autenticação Básica com o ponto de extremidade REST v1.0. Em 1º de novembro de 2019, o ponto de extremidade REST da v1.0 será totalmente desativado e a documentação da v1.0 será removida logo em seguida. Comece a fazer a migração do seu aplicativo para usar a API REST do Outlook na v1.0 do Microsoft Graph. Veja mais detalhes em nosso anúncio.

A API de Contatos do Outlook fornece acesso protegido a contatos e pastas de contatos de um usuário pelo Active Directory do Azure no Office 365 e a dados semelhantes nas contas da Microsoft, especificamente nestes domínios: Hotmail.com, Live.com, MSN.com, Outlook.com, e Passport.com.

Observação

Para simplificar a referência, o restante deste artigo usa o Outlook.com para incluir esses domínios de conta da Microsoft.

Não tem interesse na v1.0 da API? No tabela de conteúdo à esquerda, vá para a seção Referência da API REST do Office 365 e selecione a versão desejada.

Todas as operações da API de Contatos

Operações de contatos

Contatos são armazenados em pastas de contatos. Você pode obter, criar, alterar e excluir contatos.

• Obter contatos
• Sincronizar contatos e pastas de contatos
• Criar contatos
• Atualizar contatos
• Excluir contatos

Operações de pastas de contato

Pastas de contatos podem conter contatos e outras pastas de contatos. Você pode obter pastas de contatos e criar contatos em uma pasta de contatos.

• Obter pastas de contatos

Operações de foto do contato

Cada contato pode ter uma imagem de contato opcional. Você pode obter ou definir uma foto para um contato.

• Obter foto de contato
• Definir foto de contato

Ver também

• Recurso de contato da API REST
• Recursos de pasta de contato da API REST

Como usar a API REST de Contatos

Autenticação

Assim como acontece com outras APIs REST do Outlook, para cada solicitação enviada à API de Contatos você deve incluir um token de acesso válido. A obtenção de um token de acesso exige que você tenha registrado e identificado seu aplicativo e obtido a autorização adequada.

Você pode aprender mais sobre algumas opções simplificadas de registro e autorização. Tenha isso em mente ao prosseguir com as operações específicas na API de Contatos.

Versão da API

A API REST de Contatos é suportada em todas as versões da API REST do Outlook. A funcionalidade pode variar dependendo da versão específica.

Usuário destino

As solicitações da API de Contatos são sempre feitas em nome do usuário atual.

Veja Usar a API REST do Outlook para obter mais informações comuns a todos os subconjuntos da API REST do Outlook.

Obter contatos

Você pode obter uma coleção de contatos ou um único contato de uma pasta de contatos.

• Obter uma coleção de contatos
• Obter um contato

Obter uma coleção de contatos

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read
• wl.basic

Obtém uma coleção de contatos da pasta de contatos padrão do usuário conectado (.../me/contacts), ou da pasta contato especificada.

GET https://outlook.office.com/api/v1.0/me/contacts
GET https://outlook.office.com/api/v1.0/me/contactfolders/{contact_folder_id}/contacts

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_folder_id	sequência de caracteres	ID da pasta de contatos, se estiver obtendo contatos de uma pasta específica.

Observação

Por padrão, cada contato na resposta inclui todas as suas propriedades. Use $select para especificar somente as propriedades necessárias para um melhor desempenho. A propriedade Id é sempre retornada. Confira Parâmetros de consulta do OData para ver parâmetros de filtragem, classificação e paginação.

O exemplo a seguir mostra como usar $select para especificar que apenas as propriedades EmailAddresses, GivenName e Surname de cada contato sejam retornadas na resposta. Consulte o exemplo de resposta em Obter um contato para ver uma lista completa das propriedades de um contato retornadas caso você não use $select.

Exemplo de solicitação

GET https://outlook.office.com/api/v1.0/me/contacts?$select=EmailAddresses,GivenName,Surname

Exemplo de resposta

Código de status: 200

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa7\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk3AAA=",
            "GivenName": "Rob",
            "Surname": "Young",
            "EmailAddresses": [
                {
                    "Name": "roby@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "roby@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa6\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk2AAA=",
            "GivenName": "Pavel",
            "Surname": "Bansky",
            "EmailAddresses": [
                {
                    "Name": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa5\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk1AAA=",
            "GivenName": "Katie",
            "Surname": "Jordan",
            "EmailAddresses": [
                {
                    "Name": "katiej@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "katiej@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk0AAA=",
            "GivenName": "Garth",
            "Surname": "Fort",
            "EmailAddresses": [
                {
                    "Name": "garthf@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHkzAAA=",
            "GivenName": "Janet",
            "Surname": "Schorr",
            "EmailAddresses": [
                {
                    "Name": "janets@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "janets@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        }
    ]
}
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa7\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk3AAA=",
            "GivenName": "Rob",
            "Surname": "Young",
            "EmailAddresses": [
                {
                    "Name": "roby@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "roby@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa6\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk2AAA=",
            "GivenName": "Pavel",
            "Surname": "Bansky",
            "EmailAddresses": [
                {
                    "Name": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa5\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk1AAA=",
            "GivenName": "Katie",
            "Surname": "Jordan",
            "EmailAddresses": [
                {
                    "Name": "katiej@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "katiej@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk0AAA=",
            "GivenName": "Garth",
            "Surname": "Fort",
            "EmailAddresses": [
                {
                    "Name": "garthf@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHkzAAA=",
            "GivenName": "Janet",
            "Surname": "Schorr",
            "EmailAddresses": [
                {
                    "Name": "janets@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "janets@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        }
    ]
}

Tipo de resposta

A coleção de contatos solicitada.

Obter um contato

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read
• wl.basic

Obtenha um contato usando o ID do contato.

GET https://outlook.office.com/api/{version}/me/contacts/{contact_id}

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
version	sequência de caracteres	A versão da API.
contact_id	sequência de caracteres	A ID do contato.

Exemplo de solicitação

GET https://outlook.office.com/api/v1.0/me/contacts/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop

Exemplo de resposta

Código de status: 200

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts/$entity",
    "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
    "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
    "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk0AAA=",
    "DateTimeCreated": "2014-10-19T23:08:24Z",
    "DateTimeLastModified": "2014-10-19T23:08:24Z",
    "ChangeKey": "EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4",
    "Categories": [],
    "ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEOAAA=",
    "Birthday": null,
    "FileAs": "Fort, Garth",
    "DisplayName": "Garth Fort",
    "GivenName": "Garth",
    "Initials": null,
    "MiddleName": null,
    "NickName": null,
    "Surname": "Fort",
    "Title": null,
    "YomiGivenName": null,
    "YomiSurname": null,
    "YomiCompanyName": null,
    "Generation": null,
    "EmailAddresses": [
        {
            "Name": "garthf@a830edad9050849NDA1.onmicrosoft.com",
            "Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
        }
    ],
    "ImAddresses": [
        "sip:garthf@a830edad9050849nda1.onmicrosoft.com"
    ],
    "JobTitle": "Web Marketing Manager",
    "CompanyName": null,
    "Department": "Sales & Marketing",
    "OfficeLocation": "20/1101",
    "Profession": null,
    "BusinessHomePage": null,
    "AssistantName": null,
    "Manager": null,
    "HomePhones": [],
    "MobilePhone1": null,
    "BusinessPhones": [
        "+1 918 555 0101"
    ],
    "HomeAddress": {},
    "BusinessAddress": {},
    "OtherAddress": {},
    "SpouseName": null,
    "PersonalNotes": null,
    "Children": []
}

Tipo de resposta

O contato solicitado.

Observação

Por padrão, a resposta inclui todas as propriedades do contato. Use $select para especificar somente as propriedades necessárias para um melhor desempenho. A propriedade Id é sempre retornada. Confira Parâmetros de consulta do OData para ver parâmetros de filtragem, classificação e paginação.

O exemplo a seguir mostra como usar $select para especificar que apenas as propriedades EmailAddresses, GivenName, e Surname do contato sejam retornadas na resposta.

Exemplo de solicitação

GET https://outlook.office.com/api/v1.0/me/contacts/AAMkAGI2THk0AAA=?$select=EmailAddresses,GivenName,Surname

Exemplo de resposta

Código de status: 200

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
    "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
    "Id": "AAMkAGI2THk0AAA=",
    "GivenName": "Garth",
    "Surname": "Fort",
    "EmailAddresses": [
        {
            "Name": "garthf@a830edad9050849NDA1.onmicrosoft.com",
            "Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
        }
    ]
}

Sincronizar contatos e pastas de contatos

Você pode sincronizar sua lista local de contatos com os contatos no servidor. A sincronização de contatos é uma operação feita por pasta, por exemplo, você pode sincronizar todos os contatos em sua pasta de contatos raiz. Se você tiver outras pastas de Contatos, precisará sincronizar cada uma delas individualmente.

A sincronização suporta apenas a sincronização completa; Todos os contatos na pasta especificada são retornados com cada solicitação.

Sincronizar uma pasta de contatos normalmente requer duas ou mais solicitações GET. A solicitação GET é feita de maneira muito parecida com a que você obtém contatos, a diferença é que você adiciona os seguintes cabeçalhos de solicitação.

• Você deve especificar o cabeçalho Prefer: odata.track-changes em todas as suas solicitações de sincronização.

• Você pode especificar o cabeçalho Prefer: odata.maxpages = {n} para definir o número máximo de contatos retornados em cada solicitação.

  A segunda e as subsequentes solicitações GET diferem da primeira, pois incluem um deltaToken ou um skipToken recebido em uma resposta anterior.

  A resposta inicial a uma solicitação de sincronização sempre retorna um deltaToken. Você deve sempre fazer uma segunda solicitação GET usando o deltaToken para determinar se há contatos adicionais. A segunda solicitação retornará contatos adicionais e um skipToken se houver mais contatos disponíveis, ou um deltaToken se o último contato foi enviado.

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read
• wl.basic

GET https://outlook.office.com/api/v1.0/me/Contacts
GET https://outlook.office.com/api/v1.0/me/ContactFolders/{folderName}

Parâmetro obrigatório	Tipo	Descrição
Parâmetros do cabeçalho
Preferir	odata.track-changes	Indica que a solicitação é uma solicitação de sincronização.
Preferir	odata.maxpagesize	Define o número de contatos retornados em cada resposta.
Parâmetro de URL
folderName	sequência de caracteres	O nome da pasta a ser sincronizada.
odata.deltaLink	Cadeia de caracteres	O token que indica a última vez que a pasta foi sincronizada.
odata.skiptoken	Cadeia de caracteres	O token que indica que há mais mensagens para download.

Tipo de resposta

Uma coleção contendo os contatos solicitados e um deltaToken que você usa para solicitar páginas adicionais de dados de contatos do servidor e uma sincronização incremental. Se o número de contatos retornados for maior que o valor especificado no cabeçalho odata.maxpagesize a resposta será retornada em várias páginas.

A resposta incluirá um cabeçalho Preference-Applied: odata-trackchanges. Se você tentar sincronizar um recurso que não é suportado, esse cabeçalho não será retornado na resposta. Verifique esse cabeçalho antes de processar a resposta para evitar erros.

Observação

Por padrão, a resposta inclui todas as propriedades dos contatos especificados. Use $select para especificar apenas as propriedades que você precisa para o melhor desempenho. A propriedade Id é sempre retornada. Não use $filter, $orderby, $search ou $top, pois não são suportados para sincronizar contatos ou pastas de contatos. Consulte Parâmetros de consulta OData para mais detalhes.

Exemplos

Solicitação inicial para uma sincronização completa:

GET https://outlook.office.com/api/v1.0/Me/Contacts

Inclua os seguintes cabeçalhos:

• Prefer: odata.track-changes
• Prefer: odata.maxpagesize=100

Segunda solicitação para o servidor após uma solicitação de sincronização completa:

https://outlook.office.com/api/v1.0/Me/Contacts/?%24deltatoken=169ca50467d34d9fb8adb664961b9836

Inclua os seguintes cabeçalhos:

• Prefer: odata.track-changes
• Prefer: odata.maxpagesize=100

Segunda resposta do servidor com páginas adicionais disponíveis:

Cabeçalho

Preference-Applied: odata.track-changes

Corpo

@odata.deltaLink=https://outlook.office.com/api/v1.0/me/Contacts/messages/?%24skiptoken=169ca50467d34d9fb8adb664961b9836

Mensagens de conteúdo

Segunda ou subsequente resposta do servidor quando todos os contatos foram enviados:

Cabeçalho

Preference-Applied: odata.track-changes

Corpo

@odata.deltaLink=https://outlook.office.com/api/v1.0/me/Contacts/?%24deltatoken=169ca50467d34d9fb8adb664961b9836

Mensagens de conteúdo

Solicitação para o servidor quando páginas adicionais estiverem disponíveis:

https://outlook.office.com/api/v1.0/Me/Contacts/?%24skiptoken=169ca50467d34d9fb8adb664961b9836

Inclua os seguintes cabeçalhos:

• Prefer: odata.track-changes
• Prefer: odata.maxpagesize=100

Criar contatos

Crie um contato na pasta de Contatos especificada.

• Criar um contato

Criar um contato

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.readwrite
• wl.contacts_create

Adicione um contato na pasta de contatos raiz ou no ponto de extremidade de contacts de outra pasta de contatos.

POST https://outlook.office.com/api/v1.0/me/contacts
POST https://outlook.office.com/api/v1.0/me/contactfolders/{contact_folder_id}/contacts

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_folder_id	sequência de caracteres	ID da pasta de contatos, se você estiver criando um contato em uma pasta de contatos específica.
Parâmetros de corpo
GivenName	sequência de caracteres	O nome dado ao contato.

Especifique o parâmetro GivenName e quaisquer propriedades graváveis de contato no corpo da solicitação.

Exemplo de solicitação

POST https://outlook.office.com/api/v1.0/me/contacts

Content-Type: application/json

{
  "GivenName": "Pavel",
  "Surname": "Bansky",
  "EmailAddresses": [
    {
      "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "Pavel Bansky"
    }
  ],
  "BusinessPhones": [
    "+1 732 555 0102"
  ]
}

Exemplo de resposta

Código do status: 201

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"EQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAV41eC\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEOAAAmP1Ln1wcHRariNdTMGAO9AAAV4xqVAAA=",
  "ChangeKey": "EQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAV41eC",
  "Categories": [],
  "DateTimeCreated": "2014-10-22T20:38:18Z",
  "DateTimeLastModified": "2014-10-22T20:38:19Z",
  "ParentFolderId": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAAAAAEOAAA=",
  "Birthday": null,
  "FileAs": "",
  "DisplayName": "Pavel Bansky",
  "GivenName": "Pavel",
  "Initials": null,
  "MiddleName": null,
  "NickName": null,
  "Surname": "Bansky",
  "Title": null,
  "Generation": null,
  "EmailAddresses": [
    {
      "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "Pavel Bansky"
    },
    null,
    null
  ],
  "ImAddresses": [
    null,
    null,
    null
  ],
  "JobTitle": null,
  "CompanyName": null,
  "Department": null,
  "OfficeLocation": null,
  "Profession": null,
  "BusinessHomePage": null,
  "AssistantName": null,
  "Manager": null,
  "HomePhones": [
    null,
    null
  ],
  "BusinessPhones": [
    "+1 732 555 0102",
    null
  ],
  "MobilePhone1": null,
  "HomeAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "BusinessAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "OtherAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "YomiSurname": null,
  "YomiGivenName": null,
  "YomiCompanyName": null
}

Tipo de resposta

O novo contato.

Atualizar contatos

Alterar as propriedades de um contato.

• Atualizar um contato

Atualizar um contato

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.readwrite
• wl.contacts_create

Especifique quaisquer propriedades graváveis de contato no corpo da solicitação. Apenas as propriedades especificadas são alteradas.

PATCH https://outlook.office.com/api/v1.0/me/contacts/{contact_id}

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_id	sequência de caracteres	A ID do contato.

Exemplo de solicitação

PATCH https://outlook.office.com/api/v1.0/me/contacts/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHkzAAA=

Content-Type: application/json

{
  "HomeAddress": {
    "Street": "Some street",
    "City": "Seattle",
    "State": "WA",
    "PostalCode": "98121"
  },
  "Birthday": "1974-07-22"
}

Exemplo de resposta

Código de status: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3\"",
  "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHkzAAA=",
  "ChangeKey": "EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3",
  "Categories": [],
  "DateTimeCreated": "2014-10-19T23:08:18Z",
  "DateTimeLastModified": "2014-10-19T23:08:18Z",
  "ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEOAAA=",
  "Birthday": "1974-07-22T00:00:00Z",
  "FileAs": "Schorr, Janet",
  "DisplayName": "Janet Schorr",
  "GivenName": "Janet",
  "Initials": null,
  "MiddleName": null,
  "NickName": null,
  "Surname": "Schorr",
  "Title": null,
  "Generation": null,
  "EmailAddresses": [
    {
      "Address": "janets@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "janets@a830edad9050849NDA1.onmicrosoft.com"
    },
    null,
    null
  ],
  "ImAddresses": [
    "sip:janets@a830edad9050849nda1.onmicrosoft.com",
    null,
    null
  ],
  "JobTitle": "Product Marketing Manager",
  "CompanyName": null,
  "Department": "Sales & Marketing",
  "OfficeLocation": "18/2111",
  "Profession": null,
  "BusinessHomePage": null,
  "AssistantName": null,
  "Manager": null,
  "HomePhones": [
    null,
    null
  ],
  "BusinessPhones": [
    "+1 425 555 0109",
    null
  ],
  "MobilePhone1": null,
  "HomeAddress": {
    "Street": "Some street",
    "City": "Seattle",
    "State": "WA",
    "CountryOrRegion": null,
    "PostalCode": "98121"
  },
  "BusinessAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "OtherAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "YomiSurname": null,
  "YomiGivenName": null,
  "YomiCompanyName": null
}

Tipo de resposta

O contato atualizado.

Excluir contatos

Exclui um contato. O conteúdo excluído pode não ser recuperável.

Para saber mais, confira Como excluir itens usando o EWS no Exchange.

• Excluir um contato

Excluir um contato

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.readwrite
• wl.contacts_create

DELETE https://outlook.office.com/api/v1.0/me/contacts/{contact_id}

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_id	sequência de caracteres	A ID do contato.

Exemplo de solicitação

DELETE https://outlook.office.com/api/v1.0/me/contacts/AAMkAGE0Myy2hAAA=

Exemplo de resposta

Status code: 204

Obter pastas de contatos

Você pode obter uma coleção de pastas de contatos ou uma única pasta de contatos.

• Obter uma coleção de pastas de contatos
• Obter uma pasta de contatos

Obter uma coleção de pastas de contatos

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read
• wl.basic

Obtenha a coleção de pastas de contatos da pasta padrão de Contatos do usuário conectado (.../me/contactfolders), ou da pasta de contatos especificada.

GET https://outlook.office.com/api/v1.0/me/contactfolders
GET https://outlook.office.com/api/v1.0/me/contactfolders/{contact_folder_id}/childfolders

Observação

Confira Parâmetros de consulta do OData para ver parâmetros de filtragem, classificação e paginação.

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_folder_id	sequência de caracteres	ID da pasta de contatos, se você estiver obtendo pastas de contatos de uma pasta de contatos específica.

Exemplo de solicitação

GET https://outlook.office.com/api/v1.0/me/contactfolders

Exemplo de resposta

Código de status: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/ContactFolders",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAADTKI5AAA=",
      "ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEOAAA=",
      "DisplayName": "Finance"
    }
  ]
}

Tipo de resposta

A coleção de pastas de contatos solicitada.

Obter uma pasta de contatos

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read
• wl.basic

Obtenha uma pasta de contatos usando a respectiva ID.

GET https://outlook.office.com/api/v1.0/me/contactfolders/{contact_folder_id}

Observação

Confira Parâmetros de consulta do OData para ver parâmetros de filtragem, classificação e paginação.

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_folder_id	sequência de caracteres	ID da pasta de contatos.

Exemplo de solicitação

GET https://outlook.office.com/api/v1.0/me/contactfolders/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAADTKI5AAA=

Exemplo de resposta

Código de status: 200

{
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAADTKI5AAA=",
  "ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEOAAA=",
  "DisplayName": "Finance"
}

Tipo de resposta

A pasta de contatos solicitada.

Obter foto e metadados do contato

Este recurso está disponível nas versões v2.0 e beta. Para saber mais, na tabela de conteúdo à esquerda, vá para a seção Referência da API REST do Office 365 e selecione uma dessas versões.

Definir foto de contato

Este recurso está disponível nas versões v2.0 e beta. Para saber mais, na tabela de conteúdo à esquerda, vá para a seção Referência da API REST do Office 365 e selecione uma dessas versões.

Próximas etapas

Se você estiver pronto para começar a criar um aplicativo ou apenas quiser aprender mais, temos tudo o que você precisa.

• Comece com as APIs REST de Email, Calendário e Contatos.
• Quer exemplos? Nós temos.

Se preferir, aprenda mais sobre como usar a plataforma do Office 365:

• API REST do Outlook no Centro de Desenvolvimento do Outlook
• Visão geral sobre desenvolvimento na plataforma do Office 365
• Autenticação de aplicativo do Office 365 e autorização de recursos
• Registre manualmente seu aplicativo no Azure AD para que ele possa acessar as APIs do Office 365
• Referência da API de Email
• Referência da API de Calendário
• API REST de Tarefa
• API do OneDrive
• Referência de operações da API REST do Serviço de Descoberta
• Referência de recurso para as APIs REST de Email, Calendário, Contatos e Tarefa