1. 人员API列表

1.1. 新增人员

描述: 每次新增数不能超过1000条。

注意:

• 如果account中的账号传了密码，且是首次导入，则该用户会自动激活，如果没传，则需要用户自行在手机端或网站上激活。
• 作为帐号的email字段通过account字段来传，不作为帐号的email字段通过contact字段来传。
• 如果人员组织不存在，则新建该组织。

URL: /gateway/openimport/open/person/add?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "eid":String, //不必须，如果没有，则以外面的eid参数为准
    "persons": [
        { //必填,人员列表
            "name":String, //必填,姓名
            "photoUrl":String, //可选,头像URL,可访问的公网URL,默认为空
            "account": {
                "mobile":String, //可选，手机账号。如果account中的email为空，且下面phone字段也为空，那mobile字段就必须，否则创建账号不成功。如果有mobile字段，也有下面phone字段，则优先以mobile字段作为账号,phone忽略。建议下面phone和mobile只要其中一个传值即可
                "email":String, //可选，邮箱账号
                "password":String //可选，账号密码，如果传了该密码，且是首次导入，则该用户会自动激活，如果没传，则是未激活的账号，需要该用户自行激活
                },
            "phone":String, //可选,手机号码,工作圈内唯一 。如果account字段中mobile和email都为空，那这个phone就必须有，否则创建账号不成功，如果account中的mobile字段存在，则优先以mobile作为账号，phone字段忽略。建议phone和mobile只要其中一个传值即可
            "isHidePhone":String, //可选,是否在通讯录中隐藏手机号码,0: 不隐藏; 1: 隐藏,默认为0
            "department":String, //可选, 部门长名称，格式："一级部门\\二级部门\\三级部门"，如 ： "研发中心\\移动平台产品部\\开发部"，挂在根部门下面，直接传： "\\"
            "jobTitle":String, //可选,职位,默认为空
            "jobNo":String, //可选,企业工号
            "gender":String, //可选,性别,0: 不确定; 1: 男; 2: 女,默认为0
            "birthday":String, //可选,生日
            "status":String, //可选,状态 0: 注销，1: 正常，2: 禁用,默认为1
            "weights":int, //可选，排序权重，权重越小，排序越前.
            "orgUserType":int, //可选,是否部门负责人,0表示普通用户，1表示部门负责人
            "contact":jsonarray, //自定义的联系方式，可以存储公司自定义的一些个人信息，比如短号、工号等。contact是公有信息，包括电话，邮箱以及其他三类，每类必须有name,type,value三个属性，type为P支持在手机端直接呼叫打电话,具体格式: [{“name”:”工号”，“type”:”O”, “value”:”GH001”},{“name”:”电话”，“type”:”P”, “value”:”13800000000”},{"name": "邮箱1","type": "E","value": "123aaa@abc.com"}...]其中name是自定义属性的名称，type是类型，type值只有P,E,O三种类型，分别表示手机号，邮箱和其他，value是对应的值
            "hireDate":String,//入职日期，格式如："2018-01-01"
            "positiveDate":String,//转正日期，格式如："2018-01-01"
            "regSource":String //用户来源，如K3OA则对应"K3OA",EAS对应"EAS",K/3对应"K/3",KIS对应"KIS",微信对应"wechat"，S-HR对应"sHR"
        },…
    ]
}

完整JSON串示例：

{
    "eid": "30085",
    "persons": [{
        "name": "YINHONGJUN",
        "photoUrl": "",
        "account": {
            "mobile": "13750158xxx",
            "email": "xxx@163.com",
            "password": "123456"
        },
        "phone": "13750158xxx",
        "isHidePhone": 0,
        "department": "研发中心\\移动平台产品部\\开发部",
        "jobNo": "6666",
        "jobTitle": "开发工程师",
        "gender": 1,
        "birthday": "2012-12-12",
        "status": 1,
        "contact": [{
            "name": "电话",
            "type": "P",
            "value": "13800000000"
        }]
    }],
    "regSource": "K3OA"
}

输出: 参见输出结果,其中data字段格式如下：

[
    {
    "openId":String, //openId
    "msgId":String, //如果创建成功，则与openId相同值，不成功，则是手机号
    "msgCode":int, //消息码
    "msg":String //消息
    },…
]

1.2. 新增人员new

描述: 每次新增数不能超过1000条。

注意:

• 如果account中的账号传了密码，且是首次导入，则该用户会自动激活，如果没传，则需要用户自行在手机端或网站上激活。
• 作为帐号的email字段通过account字段来传，不作为帐号的email字段通过contact字段来传。
• 如果人员组织不存在，则不新建该组织

URL: /gateway/openimport/open/person/addNew?accessToken=xxxxxx

输入输出: 参见新增人员1输入输出

1.3. 更新人员信息

描述: 根据openId更新人员信息，openId字段必填，其他字段至少有一项不能为空，每次更新数不能超过1000条

注意:

• 不再支持人员的新增，新增人员请使用新增人员接口;
• 更换手机号码请使用修改手机号接口;
• 不再支持组织的新增、更改，组织的变更须使用更新人员组织接口;
• 不再支持状态的更改，状态的变更请使用更新人员状态接口;
• 需要更新的字段请将对应的key-value对传过来，不用更新的字段，请不要传递对应的key。举个例子，传"jobTitle":"" 将导致职称被清空（而不是保持职称不修改）。

URL: gateway/openimport/open/person/updateInfo?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "eid":String, //不必须，如果没有，则以外面的eid参数为准
    "persons": [
        { //必填,人员列表
        "openId":String, //必填,人员的openId
        "name":String, //可选,姓名
        "photoUrl":String, //可选,头像URL
        "isHidePhone":String, //可选,是否在通讯录中隐藏手机号码
        "jobNo":String, //可选,企业工号
        "jobTitle":String, //可选,职位
        "gender":int, //可选,性别
        "birthday":String, //可选,生日
        "weights":int, //可选，排序权重，权重越小，排序越前.
        "orgUserType":int, //可选,是否部门负责人,0表示普通用户，1表示设置部门负责人 2 表示取消部门负责人
        "hireDate":String,//入职日期，格式如："2018-01-01"
        "positiveDate":String,//转正日期，格式如："2018-01-01"
        "contact": [{
            "name": String,
            "type":String,
            "value":String
        }...] // 自定义的联系方式,更新此字段，如果是部分更新，也需要将全部字段的值也传过来，因为此字段会覆盖保存
        },…
    ]
}

输出: 参见输出结果,其中data字段格式如下：

[{
    "msgId":String, //人员的openId
    "msgCode":int, //消息码
    "msg":String //消息
},…]

1.4. 更新人员组织

描述: 根据openId更新人员组织，每次更新数不能超过1000条

URL: gateway/openimport/open/person/updateDept?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "eid":String, //不必须，如果没有，则以外面的eid参数为准
    "persons": [{ //必填,人员列表
        "openId":String, //必填,人员的openId,人员必须在职
        "department":String, //必填,新的组织长名称,组织须已存在。department=""，则人员移动到根部门;department="0",则人员移动到[无部门人员]
        },…]
}

输出: 参见输出结果,其中data字段格式如下：

[{
    "msgId":String, //人员的openId
    "msgCode":int, //消息码
    "msg":String //消息
},…]

1.5. 更新人员状态

描述: 根据openId更新人员状态，每次更新数不能超过1000条

URL: gateway/openimport/open/person/updateStatus?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "eid":String, //不必须，如果没有，则以外面的eid参数为准
    "persons": [{ //必填,人员列表
        "openId":String, //必填,人员的openId
        "type":String, //必填,详见type类型值说明表
    },…]
}

输出: 参见输出结果,其中data字段格式如下：

[{
    "msgId":String, //人员的openId
    "msgCode":int, //消息码
    "msg":String //消息
},…]

1.6. 删除人员

描述: 删除人员，根据openId删除人员，每次删除记录不能超过1000条

注意:

• 不再支持按电话删除人员

URL: gateway/openimport/open/person/delete?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "eid":String, //不必须，如果没有，则以外面的eid参数为准
    "openIds": [String,…] //必填,人员的openId数组
}

输出: 参见输出结果,其中data字段格式如下：

[{
    "msgId":String, //人员的openId
    "msgCode":int, //消息码
    "msg":String //消息
},…]

1.7. 查询全部人员信息

描述: 查询全部人员信息，查询使用分页机制，每次查询总数不能超过1000条

URL: gateway/openimport/open/person/getall?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "eid":String, //不必须，如果没有，则以外面的eid参数为准
    "begin":int, //可选,计数下标，默认0
    "count":int //可选,计数基数，默认1000
}

输出: 参见输出结果,其中data字段格式如下：

[
    { //人员列表
    "openId":String, //人员的openid
    "name":String, //姓名
    "photoUrl":String, //头像URL
    "phone":String, //手机号码
    "isHidePhone":String, //是否在通讯录中隐藏手机号码,0: 不隐藏; 1: 隐藏,默认为0
    "email":String, //邮箱
    "department":String, //组织长名称
    "jobNo":String, //企业工号
    "jobTitle":String, //职位
    "gender":int, //性别,0: 不确定; 1: 男; 2: 女
    "status":int, //状态 0: 注销，1: 正常，2: 禁用
    "orgUserType":int //是否部门负责人 0:否， 1：是
    },…
]

1.8. 查询已更新人员信息

描述: 查询某个时点后有更新的人员信息,更新的信息包括个人信息以及状态信息（正常状态变为离职状态）

URL: gateway/openimport/open/person/getAtTime?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "eid":String, //不必须，如果没有，则以外面的eid参数为准
    "time":String, //必填,查询时点，格式：“2014-08-02 01:40:38”
    "begin":int, //可选,默认0
    "count":int //可选,默认1000
}

输出: 参见输出结果,其中data字段格式如下：

[
    { //人员列表
    "openId":String, //人员的openid
    "name":String, //姓名
    "photoUrl":String, //头像URL
    "phone":String, //手机号码
    "isHidePhone":String, //是否在通讯录中隐藏手机号码,0: 不隐藏; 1: 隐藏,默认为0
    "email":String, //邮箱
    "department":String, //组织长名称
    "jobNo":String, //企业工号
    "jobTitle":String, //职位
    "gender":int, //性别,0: 不确定; 1: 男; 2: 女
    "status":int, //状态 0: 注销，1: 正常，2: 禁用
    "orgUserType":int //是否部门负责人 0:否， 1：是
    },…
]

1.9. 查询指定人员信息

描述: 根据openId或phone查询指定人员，每次不能超过1000条

URL: gateway/openimport/open/person/get?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "eid":String, //注册号
    "type":int, //0：手机号码，1：openId，默认0
    "array": [String,…] //手机号码或者openId数组
}

输出: 参见输出结果,其中data字段格式如下：

[
    { //人员列表
    "openId":String, //人员的openid
    "name":String, //姓名
    "photoUrl":String, //头像URL
    "phone":String, //手机号码
    "isHidePhone":String, //是否在通讯录中隐藏手机号码,0: 不隐藏; 1: 隐藏,默认为0
    "email":String, //邮箱
    "department":String, //组织长名称
    "orgId" : String,//组织id
    "jobNo":String, //企业工号
    "jobTitle":String, //职位
    "gender":int, //性别,0: 不确定; 1: 男; 2: 女
    "status":int, //状态 0: 注销，1: 正常，2: 禁用
    "orgUserType":int //是否部门负责人 0:否， 1：是
    },…
]

1.10. 设置或取消管理员

描述: 设置或者取消管理员身份。如果工作圈没有管理员，可以通过该接口设置一个管理员

URL: gateway/openimport/open/company/setadmin?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "eid":String, //注册号,不必须，如果没有，则以外面的eid参数为准
    "account":String, //必填，账号
    "type":int //必填，操作类型。0:取消 1:设置
}

输出: 参见输出结果,其中data字段格式如下：

{

}

1.11. 根据登陆账号和密码获取其是管理员的工作圈列表

描述: 根据登陆账号和密码获取其是管理员的工作圈列表,。

注意:

• 请求url为/openaccess/input/person/getAdminCompany
• 该接口不需要accessToken授权
• 请求头信息中需要Content-Type”:“application/json,输入参数为json

URL: https://www.yunzhijia.com/openaccess/input/person/getAdminCompany

输入:

{
    "userName":String, //账号
    "password":String //密码（明文）
}

输出: 参见输出结果,其中data字段格式如下：

[
    {
    "companyName":String, //工作圈名字
    "eid":String //工作圈eid
    }，
    {}......
]

1.12. 修改手机号

描述: 批量修改手机号，未激活用户可无条件修改，已激活用户须满足当前帐号只有一个工作圈或所在圈都有一个相同管理员，目标手机号不是云之家帐号可以修改， 修改不成功的会返回openId和失败原因;

URL: gateway/openimport/open/person/updatePhone?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "persons": [
        {
            "openId": "577f7e18e4b01f52382636fe",
            "phone": "17213658978"
        },
        {
            "openId": "577f7ae3e4b01f5238261eca",
            "phone": "17269875126"
        }
    ]
}

输出: 参见输出结果,其中data字段格式如下：

[
    {
        "msg": "openId关联失败",
        "msgCode": 111,
        "msgId": "580d9f9f00b011f84defb81"
    }
]

1.13. 获取手机号变更历史记录

描述: 获取手机号变更历史记录；

URL:/gateway/openimport/open/person/getPersonChangePhone?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "begin": 0,
    "count": 10,
    "eid": "2702604",
    "time": "2017-04-02 12:00:00"
}

输出: 参见输出结果,其中data字段格式如下：

[
    {
        "createTime": "2017-05-05 10:49:25",
        "newPhone": "17220176038",
        "eid": "2702604",
        "oldPhone": "17220176001",
        "openId": "58d273d2e4b04132cf8ad418"
    }
]

1.14. 根据组织id批量更新人员组织

描述: 通过组织id更新人员组织接口

URL: /gateway/openimport/open/person/updateDeptByDeptId?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
  "eid":String, //不必须，如果没有，则以外面的eid参数为准
  "persons": [
    { //必填,人员列表
        "openId":String, //必填,人员的openId,人员必须在职
        "orgId":String, //新的组织id,组织为空则移动到无部门
    },…]
}

输出: 参见输出结果,其中data字段格式如下：

[
  {
    "msgId":String, //人员的openId
    "msgCode":int, //消息码
    "msg":String //消息
  },…
]

1.15. 添加机密组织可见成员

描述: 根据部门Id添加机密组织可见成员，所设置部门需已设置机密组织，否则添加失败

URL: /gateway/openimport/open/person/addOrgSecretPerson?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "eid":String, //不必须，如果没有，则以外面的eid参数为准
    "orgId":String, //必须
    "secretType":int, //必须，机密组织部门对应类型，1表示隐藏部门，2表示限制该部门人员不可查看其他部门
    "openIds": [String,…] //必填,人员的openId数组（一次最多支持1000个openId）
}

输出:

{
    "success": true,
    "error": "",
    "errorCode": 100,
    "data": ""
}

1.16. 删除机密组织可见成员

描述: 根据部门Id删除机密组织可见成员，所设置部门需已设置机密组织，否则删除失败

URL: /gateway/openimport/open/person/deleteOrgSecretPerson?accessToken=xxxxxx

输入: 参见输入参数，其中data字段格式如下:

{
    "eid":String, //不必须，如果没有，则以外面的eid参数为准
    "orgId":String, //必须
    "secretType":int, //必须，机密组织部门对应类型，1表示隐藏部门，2表示限制该部门人员不可查看其他部门
    "openIds": [String,…] //必填,人员的openId数组（一次最多支持1000个openId）
}

输出:

{
    "success": true,
    "error": "",
    "errorCode": 100,
    "data": ""
}

2. FAQ

2.1. API测试工具Postman调用示例

查询全部人员信息:

查询指定人员:

2.2. 查询全部人员信息接口的分页机制

设分页为y，count为x，则begin=x(y-1);例如：count=1000时，begin=0为第一页；begin=1000为第二页；依次类推。